@col/email-templates

Versie: 1.0.0 Toegevoegd: 2026-08-06

Herkomst

De blokvolgorde en de zinnen komen uit de drie bestaande activatiemails: growerportal2/src/lib/email-templates.ts (activationEmailHtml, resetPasswordEmailHtml), floriday api/src/features/auth/emails/invitation.ts, en supplier-onboarding-vercel/src/lib/email.ts (sendActivationEmail, sendPasswordResetEmail). De opbouw bleek in alle drie identiek; alleen de zinnen verschilden — zie de vergelijkingstabel in docs/specs/2026-08-06-v8-email-templates-ontwerp.md. Dat is precies de scheiding waar EmailBlock[] (uit @col/email-shell) voor bestaat: dit item levert de vorm plus overschrijfbare standaardzinnen, niet vaste tekst.

Waarvoor

De twee mails die elke app met accounts nodig heeft: wachtwoord instellen (na het aanmaken van een account) en wachtwoord vergeten. Beide functies geven { subject, blocks: EmailBlock[] } terug, die je zelf aan buildEmail uit @col/email-shell doorgeeft.

Niet voor workflow-mails — orderbevestigingen, leveringsmeldingen, statusnotificaties. Die horen in de app zelf.

Let op de naamsverwarring. Supplier-onboarding-vercel's "uitnodiging" vraagt een externe leverancier een formulier in te vullen — dat is iets anders dan de activatiemail hier, die hoort bij het aanmaken van een account met wachtwoord. Alleen Floriday's "uitnodiging" (stel je wachtwoord in) valt onder activationEmail.

Wat je app moet leveren

EMAIL_TEMPLATES_VERSION

Uit email-fill.ts: EMAIL_TEMPLATES_VERSION: string. Welke versie in een app draait, achterhaal je met grep -rn EMAIL_TEMPLATES_VERSION src/; bijwerken gaat met npx shadcn add @col/email-templates --overwrite.

ActivationStrings

Meegeleverd: activationStringsNl en activationStringsEn, beide volledig ingevuld met de standaardzinnen (aanspreekvorm je, zie Bekende beperkingen).

activationEmail

function activationEmail(input: {
  name: string
  url: string
  expires?: string // al geformatteerd; alleen nodig als strings.linkValid om {date} vraagt
  strings: ActivationStrings
}): { subject: string; blocks: EmailBlock[] }

De blokkenreeks die eruit komt:

ResetStrings / resetEmail

Identiek van vorm aan ActivationStrings / activationEmail, met dezelfde velden en dezelfde blokkenreeks. Meegeleverd: resetStringsNl en resetStringsEn. Zie Bewuste keuzes voor waarom dit een apart bestand is in plaats van een gedeelde implementatie.

Voorbeeld

import { activationEmail, activationStringsNl } from '@/components/email/email-activation'
import { buildEmail } from '@/components/email/email-shell'

const { blocks } = activationEmail({
  name: 'Jan',
  url: 'https://app.example.com/activate/abc123',
  expires: '9 augustus 2026',
  strings: activationStringsNl,
})
// De standaard subject ('Stel je wachtwoord in') draagt geen merknaam — zie
// Bekende beperkingen. Overschrijf hem in een gedeelde postbus.
const subject = 'Coloríginz — stel je wachtwoord in'

// EmailBrand komt uit @col/email-shell, niet uit dit item — zie
// docs/items/email-shell.md voor het volledige veldoverzicht.
const brand = {
  name: 'Coloríginz',
  logo: { filename: 'logo.png', content: logoBuffer, cid: 'brand-logo', width: 140, height: 40 },
  accent: '#006799',
  accentContrast: '#ffffff',
  rule: '#0098da',
  footerText: 'Coloríginz — OZ Import BV, Aalsmeer',
}

const mail = buildEmail({
  to: 'jan@example.com',
  subject,
  brand,
  // een eigen blok toevoegen kost niets aan de kant van het item —
  // dat is precies de reden voor { subject, blocks } in plaats van een compleet Mail
  blocks: entraEnabled
    ? [...blocks, { kind: 'note', text: 'Je kunt ook inloggen met je Microsoft-account.' }]
    : blocks,
})

// mail.html, mail.text, mail.attachments -> door naar je eigen transport

Bestanden

Registry-afhankelijkheid: @col/email-shell. Eén npx shadcn add @col/email-templates installeert dus acht bestanden — deze drie plus de vijf van de romp — allemaal in components/email/. Dat is precies waarom de relatieve imports kloppen.

Gebruikt door

Vul dit bij, ook vanuit een andere repo. Dit is de enige plek waar staat wie geraakt wordt door een wijziging. Installeer je het item in een nieuwe app, voeg dan een regel toe en push naar deze repo — dat hoort bij de installatie.

Bewuste keuzes

• { subject, blocks } en geen compleet Mail. Een template die een compleet Mail teruggeeft moet een EmailBrand en een ontvanger kennen, en zodra één app iets extra's wil — Floriday toont een SSO-regel, maar alleen als Entra aanstaat — komt er een extraBlocks?-prop bij, en later een position. Met { subject, blocks } is dat arraywerk in de app ([...blocks, { kind: 'note', text: ... }]), en blijft de template testbaar zonder een EmailBrand te verzinnen.
• Een ontbrekende optionele zin betekent geen blok, niet een leeg blok. Geen linkValid meegeven levert vier blokken op, niet zes met een lege regel. Zo toont Floriday wel een vervaldatum en supplier-onboarding niet, zonder dat daar een boolean-prop voor nodig is.
• Het item rekent niet met datums. expires komt binnen als kant-en-klare string. Datumopmaak is landinstelling en tijdzone, en dus het werk van de app — net zoals buildEmail zelf ook puur blijft.
• email-activation.ts en email-reset.ts lijken sterk op elkaar en dat blijft zo — ze zijn bewust niet samengevoegd. Beide bestanden worden naar consumerende apps gekopieerd waar ze los van elkaar mogen evolueren; een gedeelde bouwfunctie zou een derde begrip introduceren om een stuk of vijftien regels rechttoe-rechtaan code te besparen.
• ignoreNotice is een paragraph, linkValid een note — geen spiegelbeeldig ontwerp, ondanks dat beide om een "extra zin, alleen als meegegeven" gaan. De shell rendert elke note in 12px gedempt grijs. Zet ignoreNotice ook als note, dan staat de geruststelling "je wachtwoord blijft ongewijzigd" in dezelfde voetnootstijl als de vervaldatum van de link — terwijl die zin bedoeld is voor de ontvanger die van de mail schrikt. Een note is metadata over de mail, een paragraph is een zin aan de lezer, en ignoreNotice is het tweede.
• fill wordt op elke string toegepast, ook op subject en button, met dezelfde waardenverzameling ({ name, date }), ook al bevatten de meegeleverde teksten daar geen plaatshouder. Dat scheelt een lijstje van welke velden wel en niet ingevuld worden — een lijstje dat bij de eerste extra string alweer niet klopt. Gevolg: een {date} in linkValid zonder dat expires is meegegeven laat fill een Error gooien in plaats van de plaatshouder letterlijk te laten staan of er een lege string van te maken.

Bekende beperkingen

• Deze twee mails zijn niet apart in een e-mailclient gecontroleerd. De clientronde die in docs/items/email-shell.md staat vastgelegd — Outlook desktop, 6 aug 2026 — gold de romp: de VML-knop, het CID-logo, de tabelopbouw. Dit item voegt daar geen HTML aan toe; het zet alleen bestaande bloktypen in een andere volgorde. Wil je het toch met eigen ogen zien, dan schrijft node scripts/build-test-emails.mjs de activatiemail per merk als .eml in tmp/, en node scripts/build-test-emails.mjs reset de reset-mail. Die bestanden komen sinds v8 uit de echte templates en niet meer uit een nagebouwde blokkenreeks.
• Alleen Nederlands en Engels. De meegeleverde zinsets zijn activationStringsNl/En en resetStringsNl/En. Een derde taal is eigen werk van de consumerende app: een object van dezelfde vorm aanmaken en meegeven aan activationEmail/resetEmail.
• Eén aanspreekvorm: je. Dat is de toon van Floriday en van growerportal2 in het Engels. Een app die u wil — zoals supplier-onboarding-vercel — geeft zijn eigen strings mee; er is geen formele variant meegeleverd.
• De bestanden staan in de map van email-shell (registry/col/email-shell/), niet in een eigen registry/col/email-templates/. Dat oogt als een opruimpuntje, maar is bewust: een template importeert EmailBlock uit email-types.ts, en in de consumerende app landen beide items in dezelfde map components/email/, dus het relatieve pad ./email-types klopt daar. Stond de bron in een eigen map, dan zou datzelfde relatieve pad in déze repo niet kloppen, en zou het item uit tsconfig.json moeten — met verlies van typecontrole en tests in de registry zelf. Raak dit niet aan bij een opruimactie zonder eerst de import-structuur te veranderen.
• Het onderwerp draagt geen merknaam. subject is gelijk aan heading (bv. "Stel je wachtwoord in") en buildEmail zet er niets voor. In een gedeelde postbus ziet een ontvanger dus een onderwerpregel zonder context over welk portaal het betreft. Een app die dat wil oplossen, geeft zijn eigen strings.subject mee — dat is precies waarom de strings een parameter zijn en geen vaste tekst.
• De standaardzinnen hebben voorlopig één afnemer. Ze zijn afgeleid uit drie apps, maar alleen floriday-middleware neemt ze naar verwachting ongewijzigd over. Overschrijft die app bij de migratie toch alle zinnen, dan is dat een signaal om te herzien of alleen de vorm gedeeld had moeten worden — kijk daar bij die migratie naar in plaats van het stilzwijgend te laten staan.