@certrev/cert-block 1.1.1 → 1.2.0-canary.1

package/src/reader/render.ts

@@ -0,0 +1,326 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * `renderReaderFace` — the certrev.com "reader" face, as the Builder card paints it (1.2.0)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * The same markup, byte for byte, as the Shopify `certrev-reader-{banner,memo,sidebar,pill}` snippets, which are the
+ * portal's canonical render of the face (the "What your reader sees" demo on certrev.com). Styling is `reader.css`
+ * (the generated reader section of the Shopify stylesheet, `READER_CSS`); this file only emits the DOM it targets.
+ * The golden tests compare the sections to the portal's golden pages, and the differential tests compare edge cases to
+ * the portal's own Liquid harness output, so the two renderers cannot drift without a test saying so.
+ *
+ * It is a NEW face, selected only by a delivered render def that says `face: 'reader'` (see `envelopeCardHtml`).
+ * Nothing in the legacy `renderCertBlock` is read or changed here.
+ *
+ * The facts are read exactly as the snippets read the same envelope:
+ *  - the card renders only with a reviewer name (the memo and sidebar too); the pill needs only a verify URL;
+ *  - the credential is each credential's `cardLabel` (else `abbreviation`), joined; the "Credential verified by CertREV"
+ *    attribution is gated on a displayed credential, and "on {date}" binds `expert.credentialVerifiedAt` and nothing
+ *    else (no fallback to the certified date: with no date only the undated, still-true attribution prints);
+ *  - the compensation cue renders ONLY when the envelope carries `expert.compensationCue`; the def cannot hide it, and
+ *    its words are fixed. `illustrative` (a CertREV preview, never a live page) fills the cue's slot with the demo's
+ *    "Illustrative example" label when the envelope has no cue; a real cue always wins the slot;
+ *  - the scope line is never hideable: the card carries it when there is no memo, the memo card and the sidebar always;
+ *  - the def's `hidden` set removes the avatars (`reviewerPhoto`), `display.showExpertPhoto === false` keeps the
+ *    silhouette and never requests the photo, `display.showAuthor === false` drops the author column.
+ *
+ * Every interpolated field is escaped and every URL passes `safeUrl`. A hostile type (a number, an object) renders as
+ * nothing, never as a throw: see `helpers.ts`.
+ */
+import { asText } from '../components/escape.js'
+import { CERTREV_LINK_REL } from '../components/rel.js'
+import { CERT_SCOPE_LINE, CERT_STRINGS_VERSION, COMPENSATED_EXPERT_CUE } from '../components/render-def.js'
+import type { CertContent } from '../contract/kernel.js'
+import { readerFace } from './face.js'
+import {
+	cleaned,
+	contains,
+	esc,
+	firstName,
+	isBlank,
+	isPresent,
+	isTruthy,
+	longDate,
+	type Rec,
+	rec,
+	safeUrl,
+	textOr,
+} from './helpers.js'
+import { readerLogo } from './logo.js'
+import { readerTokens } from './tokens.js'
+
+export type ReaderLayout = 'banner' | 'sidebar' | 'floating'
+
+/** Which of the banner's two cards to paint: both (the page default), the byline card alone, or the memo card alone. */
+export type ReaderPart = 'full' | 'header' | 'memo'
+
+export interface ReaderFaceInput {
+	/** The verified envelope's `payload.content`. */
+	readonly content: CertContent
+	/** The delivered render def (already known to say `face: 'reader'`); read for tokens and `hidden`. */
+	readonly def?: unknown
+	readonly layout: ReaderLayout
+	/** Banner only; the sidebar and the floating pill are one section each. Defaults to `full`. */
+	readonly part?: ReaderPart
+	/** The envelope's `payload.certId`, stamped as `data-certrev-cert-id` (the revalidation hook reads it). */
+	readonly certId?: string
+	/** A CertREV preview (never a live page): label a cue-less article "Illustrative example". */
+	readonly illustrative?: boolean
+}
+
+/*
+ * Every reader anchor carries the package's own link policy, `CERTREV_LINK_REL` (`nofollow sponsored noopener`), the
+ * same as the legacy faces: a Builder page's CertREV links are a vendor-required placement and must keep the
+ * sponsored/nofollow signal. The Shopify snippets (and so the portal's goldens) say `rel="noopener noreferrer"`; that is
+ * theirs, not the target. It is the ONE byte the reader differs from them in, and `reader-link-rel.test.ts` pins that:
+ * the golden and differential tests rewrite the Liquid's rel on anchors to this value and compare everything else exactly.
+ */
+
+/** What every section of one render shares: the facts read once from the envelope and the def. */
+interface Facts {
+	readonly content: Rec
+	readonly expert: Rec
+	readonly disp: Rec
+	readonly def: unknown
+	readonly certId: string
+	readonly ename: string
+	readonly hideAvatar: boolean
+	readonly showPhoto: boolean
+	/** The joined credential labels, '' when there are none. */
+	readonly creds: string
+	readonly hasCue: boolean
+	readonly illus: boolean
+	readonly noMemo: boolean
+	readonly purl: string
+	readonly vurl: string
+	readonly style: string
+	readonly fg: string
+}
+
+function readFacts(input: ReaderFaceInput): Facts {
+	const content = rec(input.content)
+	const expert = rec(content.expert)
+	const disp = rec(content.display)
+	const def = input.def
+	const rd = rec(def)
+
+	const hideAvatar = contains(rd.hidden, 'reviewerPhoto')
+	const showPhoto = disp.showExpertPhoto !== false && !hideAvatar
+
+	// POR-9738: each credential's cardLabel over its bare abbreviation, joined with ', ' (labels are not trimmed).
+	const labels: string[] = []
+	if (Array.isArray(expert.credentials)) {
+		for (const credential of expert.credentials) {
+			const cr = rec(credential)
+			const label = asText(isPresent(cr.cardLabel) ? cr.cardLabel : cr.abbreviation)
+			if (!isBlank(label)) labels.push(label)
+		}
+	}
+
+	const hasCue = isPresent(expert.compensationCue)
+	const { style, fg } = readerTokens(def)
+	return {
+		content,
+		expert,
+		disp,
+		def,
+		certId: asText(input.certId),
+		ename: textOr(expert.displayName),
+		hideAvatar,
+		showPhoto,
+		creds: labels.join(', '),
+		hasCue,
+		illus: input.illustrative === true && !hasCue,
+		noMemo: isBlank(content.memo),
+		purl: cleaned(safeUrl(expert.profileUrl)),
+		vurl: cleaned(safeUrl(content.verifyUrl)),
+		style,
+		fg,
+	}
+}
+
+/** The `<section>` open tag every reader section shares. `badge` is the `.certrev-badge` hook the revalidation reads. */
+function sectionOpen(f: Facts, badge: boolean, aria: string): string {
+	const cls = badge ? 'certrev-reader certrev-badge' : 'certrev-reader'
+	// `{% if rd %}`: any def that is not nil/false stamps its version.
+	const version = isTruthy(f.def) ? ` data-certrev-def-version="${esc(rec(f.def).v)}"` : ''
+	return (
+		`<section class="${cls}" style="${f.style}"${version} data-certrev-strings-version="${CERT_STRINGS_VERSION}" ` +
+		`data-certrev-cert-id="${esc(f.certId)}" aria-label="${esc(aria)}">`
+	)
+}
+
+const anchor = (href: string, modal: string, label: string): string =>
+	`<a href="${esc(href)}" target="_blank" rel="${CERTREV_LINK_REL}" data-certrev-modal-open${modal}>${label}</a>`
+
+/** The words the memo-less banner and the memo link row use for the profile link. */
+function profileLabel(f: Facts): string {
+	const first = cleaned(firstName(f.ename))
+	return first !== '' ? `View ${esc(first)}&rsquo;s profile` : 'View profile'
+}
+
+const credentialAria = (f: Facts): string => `Content reviewed by ${f.ename}${f.creds !== '' ? `, ${f.creds}` : ''}`
+
+/** The compensation cue's slot at the head of the scope line (memo footer, sidebar). */
+function scopeLead(f: Facts): string {
+	if (f.hasCue) return `<em>${COMPENSATED_EXPERT_CUE}</em> · `
+	if (f.illus) return '<em>Illustrative example</em> · '
+	return ''
+}
+
+const SCOPE = `<span data-ftc-line>${CERT_SCOPE_LINE}</span>`
+
+/**
+ * The muted credential line, empty when the reviewer has no displayed credential (so no "verified" claim prints).
+ *
+ * The banner's is the demo's three leaves in one `<em>`: the credential, " · ", and the attribution, which reads
+ * "Credential verified by CertREV on {date}" or, with no date, just "Credential verified by CertREV". The spans carry
+ * no style of their own. The sidebar names the credential in its bold line already, so its `<em>` is the attribution
+ * alone.
+ */
+function verifiedLine(f: Facts, withCredentials: boolean): string {
+	if (f.creds === '') return ''
+	const date = cleaned(isBlank(f.expert.credentialVerifiedAt) ? '' : longDate(f.expert.credentialVerifiedAt))
+	const on = date !== '' ? ` on ${esc(date)}` : ''
+	if (!withCredentials) return `<em>Credential verified by CertREV${on}</em>`
+	return `<em><span>${esc(f.creds)}</span> · <span>Credential verified by CertREV${on}</span></em>`
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Banner: the "Expert reviewed & certified" card, and the expert memo card beneath it
+// ─────────────────────────────────────────────────────────────────────────────
+
+function bannerCard(f: Facts): string {
+	if (f.ename === '') return ''
+	const author = rec(f.content.author)
+	const authorName = textOr(author.name)
+	const authorTitle = textOr(author.title)
+	const hasAuthor = f.disp.showAuthor !== false && authorName !== '' && authorName !== f.ename
+	const avatar = (photo: unknown, size: 'sm' | ''): string =>
+		f.hideAvatar ? '' : readerFace({ photo, show: f.showPhoto, size, width: 84 })
+
+	const authorBy = hasAuthor
+		? `<div class="certrev-r-by">${avatar(author.photoUrl, 'sm')}<div>\n              <b>${esc(authorName)}</b>` +
+			`${authorTitle !== '' ? `<em>${esc(authorTitle)}</em>` : ''}<span class="certrev-r-role">Written by</span>\n            </div>\n          </div>`
+		: ''
+	const expertBy =
+		`<div class="certrev-r-by">${avatar(f.expert.photoUrl, '')}<div>\n            <b>${esc(f.ename)}</b>` +
+		`${verifiedLine(f, true)}<span class="certrev-r-role on">Reviewed by</span>\n          </div>\n        </div>`
+
+	const certifiedAt = f.content.certifiedAt
+	const certified = isBlank(certifiedAt) ? '' : cleaned(longDate(certifiedAt))
+
+	// A memo-less article gets the profile and certificate row, so the certificate stays reachable.
+	let links = ''
+	if (f.noMemo && (f.purl !== '' || f.vurl !== '')) {
+		links =
+			'<div class="certrev-r-links">' +
+			(f.purl !== '' ? anchor(f.purl, '="expert"', profileLabel(f)) : '') +
+			(f.vurl !== '' ? anchor(f.vurl, '', 'View certificate') : '') +
+			'</div>'
+	}
+
+	const hasFoot = certified !== '' || f.hasCue || f.illus
+	const rule = hasFoot || f.noMemo ? '<div class="certrev-r-rule"></div>' : ''
+
+	let foot = ''
+	if (hasFoot) {
+		const when =
+			certified !== ''
+				? `<span><em>Certified</em><time datetime="${esc(certifiedAt)}">${esc(certified)}</time></span>`
+				: '<span></span>'
+		let cue = ''
+		if (f.hasCue) {
+			cue = `<span>Compensated ${f.purl !== '' ? anchor(f.purl, '="expert"', 'expert') : 'expert'}</span>`
+		} else if (f.illus) {
+			cue = '<span>Illustrative example</span>'
+		}
+		foot = `<div class="certrev-r-foot">${when}${cue}</div>`
+	}
+
+	// POR-9317: the memo card carries the scope line when there is a memo; with none this card is the sole claim face.
+	const scope = f.noMemo ? `<div class="certrev-r-scope" data-ftc-disclosure>${SCOPE}</div>` : ''
+
+	return (
+		`${sectionOpen(f, true, credentialAria(f))}\n  <div class="certrev-r-card">\n` +
+		`    <div class="certrev-r-cap">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed &amp; certified</div>\n` +
+		`    <div class="certrev-r-cap-body">\n      <div class="certrev-r-bys${hasAuthor ? '' : ' solo'}">${authorBy}${expertBy}\n      </div>` +
+		`${links}${rule}${foot}${scope}</div>\n  </div>\n</section>`
+	)
+}
+
+function bannerMemo(f: Facts): string {
+	if (f.ename === '' || isBlank(f.content.memo)) return ''
+	const links =
+		f.purl !== '' || f.vurl !== ''
+			? '<div class="certrev-r-links">' +
+				(f.purl !== '' ? anchor(f.purl, '="expert"', profileLabel(f)) : '') +
+				(f.vurl !== '' ? anchor(f.vurl, '', 'View certificate') : '') +
+				'</div>'
+			: ''
+	const avatar = f.hideAvatar ? '' : readerFace({ photo: f.expert.photoUrl, show: f.showPhoto, size: 'lg', width: 112 })
+	return (
+		`${sectionOpen(f, false, `Expert memo by ${f.ename}`)}\n  <div class="certrev-r-card pad">\n` +
+		'    <div class="certrev-r-kick">Expert memo</div>\n' +
+		`    <div class="certrev-r-memo">${avatar}<div>\n` +
+		`        <div class="certrev-r-memo-name"><b>${esc(f.ename)}</b>${f.creds !== '' ? `, ${esc(f.creds)}` : ''}</div>\n` +
+		`        <blockquote>${esc(f.content.memo)}</blockquote>${links}</div>\n    </div>\n` +
+		'    <div class="certrev-r-rule"></div>\n    <div class="certrev-r-vfoot">\n' +
+		`      <span class="certrev-r-verified">${readerLogo('mono', 17, '')}Verified by <b>CertREV</b></span>\n` +
+		`      <span class="certrev-r-scope" data-ftc-disclosure>${scopeLead(f)}${SCOPE}</span>\n    </div>\n  </div>\n</section>`
+	)
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Sidebar and floating pill
+// ─────────────────────────────────────────────────────────────────────────────
+
+function sidebar(f: Facts): string {
+	if (f.ename === '') return ''
+	const bio = f.disp.showBio !== false && !isBlank(f.expert.bio) ? asText(f.expert.bio) : ''
+	const avatar = f.hideAvatar ? '' : readerFace({ photo: f.expert.photoUrl, show: f.showPhoto, size: 'lg', width: 112 })
+	const both = f.purl !== '' && f.vurl !== ''
+	const links =
+		f.purl !== '' || f.vurl !== ''
+			? `<div class="certrev-r-side-links${both ? '' : ' single'}">` +
+				(f.purl !== '' ? anchor(f.purl, '="expert"', 'View Profile') : '') +
+				(f.vurl !== '' ? anchor(f.vurl, '', 'View Certificate') : '') +
+				'</div>'
+			: ''
+	return (
+		`${sectionOpen(f, true, credentialAria(f))}\n  <div class="certrev-r-side">\n` +
+		`    <div class="certrev-r-cap center">${readerLogo(f.fg === '#ffffff' ? 'white' : 'mono', 18, 'CertREV')}Expert reviewed</div>\n` +
+		`    <div class="certrev-r-side-body">\n      <div class="certrev-r-by">${avatar}<div>\n` +
+		`          <b>${esc(f.ename)}${f.creds !== '' ? `, ${esc(f.creds)}` : ''}</b>${verifiedLine(f, false)}</div>\n      </div>` +
+		`${bio !== '' ? `<p>${esc(bio)}</p>` : ''}` +
+		`${isBlank(f.content.memo) ? '' : `<blockquote>${esc(f.content.memo)}</blockquote>`}` +
+		`<div class="certrev-r-scope" data-ftc-disclosure>${scopeLead(f)}${SCOPE}</div>\n    </div>` +
+		`${links}</div>\n</section>`
+	)
+}
+
+function pill(f: Facts): string {
+	if (f.vurl === '') return ''
+	const profile = f.purl !== '' ? `${anchor(f.purl, '="expert"', 'Profile')}<i aria-hidden="true">·</i>` : ''
+	return (
+		`${sectionOpen(f, true, 'Expert reviewed')}\n  <div class="certrev-r-pill">\n    <span>Expert reviewed:</span>` +
+		`${profile}${anchor(f.vurl, '', 'Certificate')}\n  </div>\n</section>`
+	)
+}
+
+/**
+ * The reader face's HTML for one layout. '' where the face paints nothing (no reviewer name; a pill with no safe
+ * verify URL; a banner `part` that has no block): the caller treats '' as "render nothing", never as an empty section.
+ *
+ * A def with no `layout` meaning here (`custom`, or any value that is not banner, sidebar or floating) is the
+ * caller's to resolve before it calls: this takes the layout it will paint.
+ */
+export function renderReaderFace(input: ReaderFaceInput): string {
+	const f = readFacts(input)
+	if (input.layout === 'sidebar') return sidebar(f)
+	if (input.layout === 'floating') return pill(f)
+	const part = input.part ?? 'full'
+	if (part === 'header') return bannerCard(f)
+	if (part === 'memo') return bannerMemo(f)
+	return [bannerCard(f), bannerMemo(f)].filter((block) => block !== '').join('\n')
+}

package/src/reader/tokens.ts

@@ -0,0 +1,93 @@
+/**
+ * `certrev-reader-tokens`: the four CSS custom properties a reader section carries on its root, from the render def.
+ *
+ *   --cr-ba     the accent the card cap and pill paint: the def's `barInk`, else its `accentColor`, else navy
+ *   --cr-ba-fg  the ink on that accent: white, or `#141414` when the def baked it for the colour that painted
+ *   --cr-br     the corner radius
+ *   --cr-bf     the font stack for the brand's `fontSlot`
+ *
+ * The values land inside a double-quoted `style` attribute, and they are held to the allow-list the Liquid snippet and
+ * the PHP twin's def parser hold them to: a colour is `#RGB` or `#RRGGBB`, a radius one non-negative px / rem / em / %
+ * length or a bare `0`, and anything else paints the default (navy, 14px). A denylist of characters is not enough: a
+ * quote, a backslash, a comment opener or a bracket left in a value hides the `;` that ends it and swallows the
+ * declarations after it. The variable names are the reader stylesheet's (`reader.css`), which `.certrev-reader`
+ * declares defaults for.
+ */
+import { asText } from '../components/escape.js'
+import { esc, rec, textOr } from './helpers.js'
+
+/** The accent when the def has none: CertREV navy. */
+const DEFAULT_ACCENT = '#0A1B3F'
+const DEFAULT_RADIUS = '14px'
+/** The foreground the def bakes for a light accent; anything else is the white default. */
+const DARK_INK = '#141414'
+
+/**
+ * The font stack per `fontSlot`, in one table so the Liquid `certrev-reader-tokens` snippet and this one are compared
+ * on a single list. An unknown or missing slot is the sans stack, as in the snippet. The serif and grotesk stacks name
+ * the reader's own `@font-face` aliases first ("CertREV Reader Serif" / "CertREV Reader Grotesk", declared in
+ * `reader.css`), then the legacy family and the generic fallbacks, as the snippet's `--cr-bf` does.
+ */
+function fontStack(slot: string): string {
+	switch (slot) {
+		case 'serif':
+			return "'CertREV Reader Serif', 'Playfair Display', ui-serif, Georgia, serif"
+		case 'grotesk':
+			return "'CertREV Reader Grotesk', 'Plus Jakarta Sans', ui-sans-serif, system-ui, sans-serif"
+		case 'mono':
+			return "'JetBrains Mono', ui-monospace, monospace"
+		case 'system':
+			return "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+		default:
+			return "'DM Sans', ui-sans-serif, system-ui, sans-serif"
+	}
+}
+
+/** A colour is `#` and then 3 or 6 hex digits (ASCII only, no trailing newline), else '' (which the caller defaults). */
+const HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+/**
+ * A radius is a bare `0`, or digits with at most one `.` (not trailing) and then px, rem, em or %, else ''. `\d` is
+ * ASCII here (no `u` flag), as the snippet's `0123456789.` is; the unit is case-sensitive.
+ */
+const LENGTH = /^(?:\d+|\d+\.\d+|\.\d+)(?:px|rem|em|%)$/
+
+/** A colour token that is a hex colour, or '' (which the caller defaults). */
+function hexColour(value: unknown): string {
+	const text = textOr(value)
+	return HEX.test(text) ? text : ''
+}
+
+/** A radius token that is a bare 0 or a non-negative length, or '' (which the caller defaults). */
+function radius(value: unknown): string {
+	const text = textOr(value)
+	return text === '0' || LENGTH.test(text) ? text : ''
+}
+
+export interface ReaderTokens {
+	/** The value of the section's `style` attribute. */
+	readonly style: string
+	/** The ink on the accent: `#ffffff` or `#141414`. The logo is white on the first and mono on the second. */
+	readonly fg: string
+}
+
+export function readerTokens(def: unknown): ReaderTokens {
+	const rd = rec(def)
+	const tokens = rec(rd.tokens)
+
+	const barInk = hexColour(tokens.barInk)
+	const accent = hexColour(tokens.accentColor)
+	const ba = barInk || accent || DEFAULT_ACCENT
+
+	// The ink follows the value that painted the accent: a def with a bar ink takes the foreground baked for it
+	// (barInkFg); one that paints its accent colour takes the one baked for that colour (accentFg).
+	let fg = '#ffffff'
+	if (barInk !== '') {
+		if (rd.barInkFg === DARK_INK) fg = DARK_INK
+	} else if (accent !== '' && rd.accentFg === DARK_INK) {
+		fg = DARK_INK
+	}
+
+	const br = radius(tokens.cornerRadius) || DEFAULT_RADIUS
+	const bf = fontStack(asText(tokens.fontSlot))
+	return { style: `--cr-ba:${esc(ba)};--cr-ba-fg:${fg};--cr-br:${esc(br)};--cr-bf:${bf}`, fg }
+}

package/src/verify/get-verified-delivery.ts

@@ -99,7 +99,7 @@ const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'obj
  */
 export function parseRenderDef(value: unknown): CertChromeRenderDef | null {
 	if (!isRecord(value)) return null
-	const { v, preset, rung, tokens, hidden, barInkFg, layout, customFace } = value
+	const { v, preset, rung, tokens, hidden, barInkFg, accentFg, face: faceName, layout, customFace } = value
 	if (typeof v !== 'number' || !Number.isFinite(v)) return null
 	if (!isString(preset) || !isString(rung) || !isRecord(tokens)) return null
 	if (!Array.isArray(hidden) || !hidden.every(isString)) return null
@@ -121,6 +121,10 @@ export function parseRenderDef(value: unknown): CertChromeRenderDef | null {
 		rung,
 		tokens: tokenOut,
 		...(barInkFg === '#141414' || barInkFg === '#ffffff' ? { barInkFg } : {}),
+		// 1.2.0: the reader face's two keys. 1.1.x dropped both; they are kept only when well-formed, so a def that
+		// carries neither parses to exactly the object 1.1.1 returned for it.
+		...(accentFg === '#141414' || accentFg === '#ffffff' ? { accentFg } : {}),
+		...(isString(faceName) ? { face: faceName } : {}),
 		hidden: [...hidden],
 		...(layout !== undefined ? { layout } : {}),
 		...(face ? { customFace: face } : {}),