Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
+73
@@ -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>
|
||||
);
|
||||
}
|
||||
+53
@@ -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>
|
||||
);
|
||||
}
|
||||
+24
@@ -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>;
|
||||
}
|
||||
+66
@@ -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>
|
||||
);
|
||||
}
|
||||
+42
@@ -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>
|
||||
);
|
||||
}
|
||||
+28
@@ -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>;
|
||||
}
|
||||
+14
@@ -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, 'Segoe UI', Roboto, 'Helvetica Neue', 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, 'Segoe UI', Roboto, 'Helvetica Neue', 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)."
|
||||
`;
|
||||
+7
@@ -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";
|
||||
+98
@@ -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");
|
||||
});
|
||||
});
|
||||
+51
@@ -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 };
|
||||
}
|
||||
Reference in new issue
Block a user