Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,73 @@
import type { CSSProperties, ReactNode } from "react";
import { Header } from "./Header.js";
import { Footer } from "./Footer.js";
import type { MailBrand } from "./theme.js";
/**
* BaseLayout — root layout for transactional emails. Renders a 560px
* centred card with brand-themed header and footer, plus a hidden
* preview-text harvested by Gmail/Apple Mail as the inbox snippet.
*/
export interface BaseLayoutProps {
readonly brand: MailBrand;
readonly title: string;
readonly previewText?: string;
readonly unsubscribeUrl?: string;
readonly children: ReactNode;
}
const bodyStyle = (brand: MailBrand): CSSProperties => ({
margin: 0,
padding: 0,
backgroundColor: brand.backgroundColor,
color: brand.textColor,
fontFamily: brand.fontFamily,
fontSize: "16px",
lineHeight: "1.5",
});
const containerStyle: CSSProperties = {
width: "100%",
maxWidth: "560px",
margin: "0 auto",
padding: "24px 16px",
};
const cardStyle = (brand: MailBrand): CSSProperties => ({
backgroundColor: brand.surfaceColor,
border: `1px solid ${brand.borderColor}`,
borderRadius: "20px",
padding: "32px",
});
const previewStyle: CSSProperties = {
display: "none",
fontSize: "1px",
lineHeight: "1px",
maxHeight: 0,
maxWidth: 0,
opacity: 0,
overflow: "hidden",
} as CSSProperties;
export function BaseLayout({ brand, title, previewText, unsubscribeUrl, children }: BaseLayoutProps) {
return (
<html lang="en">
<head>
<meta charSet="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>{title}</title>
</head>
<body style={bodyStyle(brand)}>
{previewText ? <div style={previewStyle}>{previewText}</div> : null}
<div style={containerStyle}>
<div style={cardStyle(brand)}>
<Header brand={brand} />
{children}
<Footer brand={brand} unsubscribeUrl={unsubscribeUrl} />
</div>
</div>
</body>
</html>
);
}
@@ -0,0 +1,53 @@
import type { CSSProperties, ReactNode } from "react";
import type { MailBrand } from "./theme.js";
/**
* Button — CTA-Button with brand-color theming. Validates href as
* https:// or mailto: to block javascript:/data: URL injection
* (magic-link phishing class).
*/
export interface ButtonProps {
readonly href: string;
readonly brand: MailBrand;
readonly children: ReactNode;
}
const ALLOWED_PROTOCOLS = ["https:", "mailto:"] as const;
export class InvalidActionUrlError extends Error {
constructor(public readonly url: string) {
super(`Refusing to render unsafe action URL: ${url}. Only https:// and mailto: are allowed.`);
this.name = "InvalidActionUrlError";
}
}
export function assertSafeUrl(url: string): void {
let parsed: URL;
try {
parsed = new URL(url);
} catch {
throw new InvalidActionUrlError(url);
}
if (!ALLOWED_PROTOCOLS.includes(parsed.protocol as (typeof ALLOWED_PROTOCOLS)[number])) {
throw new InvalidActionUrlError(url);
}
}
export function Button({ href, brand, children }: ButtonProps) {
assertSafeUrl(href);
const style: CSSProperties = {
display: "inline-block",
backgroundColor: brand.primaryColor,
color: brand.primaryTextColor,
padding: "12px 22px",
borderRadius: "999px",
fontWeight: 700,
fontSize: "15px",
textDecoration: "none",
};
return (
<a href={href} style={style} target="_blank" rel="noopener noreferrer">
{children}
</a>
);
}
@@ -0,0 +1,24 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Eyebrow — small uppercase label rendered above the main heading.
* Used to communicate category (e.g. "Welcome", "Password reset").
*/
export interface EyebrowProps {
readonly brand: MailBrand;
readonly children: string;
}
const style = (brand: MailBrand): CSSProperties => ({
color: brand.mutedTextColor,
fontSize: "13px",
fontWeight: 700,
letterSpacing: "0.08em",
textTransform: "uppercase",
marginBottom: "8px",
});
export function Eyebrow({ brand, children }: EyebrowProps) {
return <div style={style(brand)}>{children}</div>;
}
@@ -0,0 +1,66 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Footer — legal links (privacy, terms, imprint) and support contact.
* Required for DSGVO/CAN-SPAM compliance.
*/
export interface FooterProps {
readonly brand: MailBrand;
readonly unsubscribeUrl?: string;
}
const wrapperStyle: CSSProperties = {
marginTop: "24px",
paddingTop: "16px",
borderTop: "1px solid",
fontSize: "12px",
lineHeight: "1.5",
};
const linkStyle = (color: string): CSSProperties => ({
textDecoration: "underline",
color,
});
export function Footer({ brand, unsubscribeUrl }: FooterProps) {
return (
<div style={{ ...wrapperStyle, borderTopColor: brand.borderColor, color: brand.mutedTextColor }}>
<div>
{brand.privacyUrl ? (
<a href={brand.privacyUrl} style={linkStyle(brand.linkColor)}>
Privacy
</a>
) : null}
{brand.privacyUrl && brand.termsUrl ? <span style={{ margin: "0 6px" }}>·</span> : null}
{brand.termsUrl ? (
<a href={brand.termsUrl} style={linkStyle(brand.linkColor)}>
Terms
</a>
) : null}
{(brand.privacyUrl || brand.termsUrl) && brand.imprintUrl ? (
<span style={{ margin: "0 6px" }}>·</span>
) : null}
{brand.imprintUrl ? (
<a href={brand.imprintUrl} style={linkStyle(brand.linkColor)}>
Imprint
</a>
) : null}
</div>
{unsubscribeUrl ? (
<div style={{ marginTop: "8px" }}>
<a href={unsubscribeUrl} style={linkStyle(brand.linkColor)}>
Unsubscribe
</a>
</div>
) : null}
<div style={{ marginTop: "8px" }}>
Questions? Email us at{" "}
<a href={`mailto:${brand.supportEmail}`} style={linkStyle(brand.linkColor)}>
{brand.supportEmail}
</a>
.
</div>
</div>
);
}
@@ -0,0 +1,42 @@
import type { CSSProperties } from "react";
import type { MailBrand } from "./theme.js";
/**
* Header — brand logo (if configured) or product-name wordmark.
* Stays inline-styled to survive Outlook/Gmail HTML scrubbers.
*/
export interface HeaderProps {
readonly brand: MailBrand;
}
const headerStyle: CSSProperties = {
paddingBottom: "16px",
textAlign: "left",
};
const logoStyle: CSSProperties = {
display: "block",
border: 0,
borderRadius: "12px",
};
export function Header({ brand }: HeaderProps) {
if (brand.logoUrl) {
return (
<div style={headerStyle}>
<img
src={brand.logoUrl}
alt={brand.productName}
width={48}
height={48}
style={logoStyle}
/>
</div>
);
}
return (
<div style={headerStyle}>
<strong style={{ color: brand.textColor, fontSize: "18px" }}>{brand.productName}</strong>
</div>
);
}
@@ -0,0 +1,28 @@
import type { CSSProperties, ReactNode } from "react";
import type { MailBrand } from "./theme.js";
/**
* InfoBox — boxed section for important notices (e.g. "this link expires
* in 15 minutes", "if you didn't request this, ignore the email").
*/
export interface InfoBoxProps {
readonly brand: MailBrand;
readonly tone?: "info" | "warning";
readonly children: ReactNode;
}
const baseStyle: CSSProperties = {
marginTop: "20px",
padding: "14px 16px",
borderRadius: "10px",
fontSize: "14px",
lineHeight: "1.55",
};
export function InfoBox({ brand, tone = "info", children }: InfoBoxProps) {
const style: CSSProperties =
tone === "warning"
? { ...baseStyle, backgroundColor: "#fef3c7", color: "#92400e", border: "1px solid #fde68a" }
: { ...baseStyle, backgroundColor: "#f1f5f9", color: brand.textColor, border: `1px solid ${brand.borderColor}` };
return <div style={style}>{children}</div>;
}
@@ -0,0 +1,14 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
exports[`BaseLayout > applies tenant brand overrides (logo + primary color) 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="preload" as="image" href="https://cdn.acme.test/logo.png"/><title>Hi</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">snippet</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><img src="https://cdn.acme.test/logo.png" alt="Acme" width="48" height="48" style="display:block;border:0;border-radius:12px"/></div><p>Body</p><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`BaseLayout > renders default-brand snapshot 1`] = `"<!DOCTYPE html><html lang="en"><head><meta charSet="utf-8"/><meta name="viewport" content="width=device-width, initial-scale=1"/><title>Hello</title></head><body style="margin:0;padding:0;background-color:#f4f5f7;color:#0f172a;font-family:ui-sans-serif, -apple-system, BlinkMacSystemFont, &#x27;Segoe UI&#x27;, Roboto, &#x27;Helvetica Neue&#x27;, Arial, sans-serif;font-size:16px;line-height:1.5"><div style="display:none;font-size:1px;line-height:1px;max-height:0;max-width:0;opacity:0;overflow:hidden">A preview</div><div style="width:100%;max-width:560px;margin:0 auto;padding:24px 16px"><div style="background-color:#ffffff;border:1px solid #e2e8f0;border-radius:20px;padding:32px"><div style="padding-bottom:16px;text-align:left"><strong style="color:#0f172a;font-size:18px">ToolCTRL</strong></div><div style="color:#475569;font-size:13px;font-weight:700;letter-spacing:0.08em;text-transform:uppercase;margin-bottom:8px">Eyebrow</div><h1>Title</h1><div style="margin-top:24px;padding-top:16px;border-top:1px solid;font-size:12px;line-height:1.5;border-top-color:#e2e8f0;color:#475569"><div><a href="https://tool-ctrl.de/privacy" style="text-decoration:underline;color:#2563eb">Privacy</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/terms" style="text-decoration:underline;color:#2563eb">Terms</a><span style="margin:0 6px">·</span><a href="https://tool-ctrl.de/imprint" style="text-decoration:underline;color:#2563eb">Imprint</a></div><div style="margin-top:8px">Questions? Email us at <a href="mailto:info@tool-ctrl.de" style="text-decoration:underline;color:#2563eb">info@tool-ctrl.de</a>.</div></div></div></div></body></html>"`;
exports[`BaseLayout > renders default-brand snapshot 2`] = `
"A preview
ToolCTRL
Eyebrow
Title
Privacy (https://tool-ctrl.de/privacy)·Terms (https://tool-ctrl.de/terms)·Imprint (https://tool-ctrl.de/imprint)
Questions? Email us at info@tool-ctrl.de (mailto:info@tool-ctrl.de)."
`;
@@ -0,0 +1,7 @@
export { BaseLayout, type BaseLayoutProps } from "./BaseLayout.js";
export { Header, type HeaderProps } from "./Header.js";
export { Footer, type FooterProps } from "./Footer.js";
export { Button, InvalidActionUrlError, assertSafeUrl, type ButtonProps } from "./Button.js";
export { InfoBox, type InfoBoxProps } from "./InfoBox.js";
export { Eyebrow, type EyebrowProps } from "./Eyebrow.js";
export { defaultMailBrand, withBrandDefaults, type MailBrand } from "./theme.js";
@@ -0,0 +1,98 @@
import { describe, expect, test } from "vitest";
import { renderReactEmail } from "../render-helpers.js";
import { BaseLayout } from "./BaseLayout.js";
import { Button, InvalidActionUrlError } from "./Button.js";
import { Eyebrow } from "./Eyebrow.js";
import { InfoBox } from "./InfoBox.js";
import { defaultMailBrand, withBrandDefaults } from "./theme.js";
describe("BaseLayout", () => {
test("renders default-brand snapshot", () => {
const result = renderReactEmail(
<BaseLayout brand={defaultMailBrand} title="Hello" previewText="A preview">
<Eyebrow brand={defaultMailBrand}>Eyebrow</Eyebrow>
<h1>Title</h1>
</BaseLayout>
);
expect(result.html).toMatchSnapshot();
expect(result.text).toMatchSnapshot();
});
test("applies tenant brand overrides (logo + primary color)", () => {
const brand = withBrandDefaults({
productName: "Acme",
logoUrl: "https://cdn.acme.test/logo.png",
primaryColor: "#123456",
tenantName: "Acme Inc",
});
const result = renderReactEmail(
<BaseLayout brand={brand} title="Hi" previewText="snippet">
<p>Body</p>
</BaseLayout>
);
expect(result.html).toContain("https://cdn.acme.test/logo.png");
expect(result.html).toContain("Acme");
expect(result.html).toMatchSnapshot();
});
});
describe("Button safety", () => {
test("renders https CTA", () => {
const { html } = renderReactEmail(
<Button brand={defaultMailBrand} href="https://example.com/go">
Go
</Button>
);
expect(html).toContain('href="https://example.com/go"');
});
test("allows mailto: CTA", () => {
const { html } = renderReactEmail(
<Button brand={defaultMailBrand} href="mailto:hi@example.com">
Mail
</Button>
);
expect(html).toContain('href="mailto:hi@example.com"');
});
test.each(["javascript:alert(1)", "http://insecure.test", "data:text/html,<script>", "not a url"])(
"rejects unsafe href %s",
(href) => {
expect(() =>
renderReactEmail(
<Button brand={defaultMailBrand} href={href}>
X
</Button>
)
).toThrow(InvalidActionUrlError);
}
);
});
describe("InfoBox", () => {
test("renders info tone", () => {
const { html } = renderReactEmail(
<InfoBox brand={defaultMailBrand}>Note</InfoBox>
);
expect(html).toContain("Note");
});
test("renders warning tone with accent palette", () => {
const { html } = renderReactEmail(
<InfoBox brand={defaultMailBrand} tone="warning">
Heads up
</InfoBox>
);
expect(html).toContain("Heads up");
expect(html).toMatch(/#fef3c7/i);
});
});
describe("Eyebrow", () => {
test("uppercases via CSS, not value", () => {
const { html } = renderReactEmail(<Eyebrow brand={defaultMailBrand}>welcome</Eyebrow>);
// The visible text is unchanged; transform happens via CSS.
expect(html).toContain(">welcome<");
expect(html).toContain("text-transform:uppercase");
});
});
@@ -0,0 +1,51 @@
/**
* Default brand-theme tokens for React-Email transactional templates.
*
* Templates accept a `brand` prop derived from `@toolctrl/brand`'s
* `BrandTokens`. When undefined we fall back to these defaults so
* preview/storybook renders stay deterministic regardless of tenant
* configuration. Keep this aligned with `packages/brand/src/index.ts`.
*/
export interface MailBrand {
readonly productName: string;
readonly logoUrl?: string;
readonly primaryColor: string;
readonly primaryTextColor: string;
readonly textColor: string;
readonly mutedTextColor: string;
readonly backgroundColor: string;
readonly surfaceColor: string;
readonly borderColor: string;
readonly linkColor: string;
readonly fontFamily: string;
readonly supportEmail: string;
readonly supportFromName: string;
readonly privacyUrl?: string;
readonly termsUrl?: string;
readonly imprintUrl?: string;
readonly tenantName?: string;
}
export const defaultMailBrand: MailBrand = {
productName: "ToolCTRL",
primaryColor: "#2563eb",
primaryTextColor: "#ffffff",
textColor: "#0f172a",
mutedTextColor: "#475569",
backgroundColor: "#f4f5f7",
surfaceColor: "#ffffff",
borderColor: "#e2e8f0",
linkColor: "#2563eb",
fontFamily:
"ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif",
supportEmail: "info@tool-ctrl.de",
supportFromName: "ToolCTRL Support",
privacyUrl: "https://tool-ctrl.de/privacy",
termsUrl: "https://tool-ctrl.de/terms",
imprintUrl: "https://tool-ctrl.de/imprint",
} as const;
export function withBrandDefaults(override?: Partial<MailBrand>): MailBrand {
if (!override) return defaultMailBrand;
return { ...defaultMailBrand, ...override };
}