shellscape · shellscape · Dec 18, 2023 · Dec 18, 2023 · Dec 18, 2023 · Dec 18, 2023
diff --git a/docs/components/color-scheme.md b/docs/components/color-scheme.md
@@ -0,0 +1,61 @@
+---
+title: 'ColorScheme'
+description: A JSX email component which provides meta and style foundations for color scheme support
+slug: color-scheme
+type: component
+---
+
+<!--@include: @/include/header.md-->
+
+::: tip
+Please be sure to read our FAQ about Dark Mode in the context of email templates: https://jsx.email/docs/faq#dark-and-light-mode
+:::
+
+<!--@include: @/include/install.md-->
+
+## Usage
+
+Add the component to your email template.
+
+```jsx
+import { Body, ColorScheme, Head, Html } from 'jsx-email';
+
+const Email = () => {
+  return (
+    <Html>
+      <Head>
+        <ColorScheme mode="light only" />
+      </Head>
+      <Body></Body>
+    </Html>
+  );
+};
+```
+
+## Component Props
+
+```ts
+export interface ColorSchemeProps {
+  mode?: Mode;
+}
+```
+
+### Individual Props
+
+```ts
+mode?: ColorSchemeMode;
+```
+
+Default: `'normal'`<br/>
+
+Selects the color scheme mode that informs the email client which mode to render.
+
+Supported Values:
+
+- `'dark'`
+- `'dark only'` The email client will only ever render the content in the dark color scheme and forbids the email client from overriding the color scheme.
+- `'light'`
+- `'light dark'` The email client will choose the light or dark theme to match the user’s preference. If the user’s preference does not match something in the list, the email client will choose which mode to display.
+- `'light dark only'` The email client will choose the first of the listed schemes that it supports taking user preference into account and forbids the email client from overriding the color scheme.
+- `'light only'` The email client will only ever render the content in the light color scheme and forbids the email client from overriding the color scheme.
+- `'normal'` Indicates that the email supports the page's supported color schemes, if they are set, or that it supports no color schemes at all otherwise.
diff --git a/docs/components/html.md b/docs/components/html.md
@@ -43,4 +43,4 @@ Identify the direction of text content on the email
 
 :::tip
 This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'html'>`.
-:::
+:::
diff --git a/docs/components/image.md b/docs/components/image.md
@@ -63,5 +63,3 @@ The width of an image in pixels
 ::: tip
 This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'img'>`.
 :::
-
-
diff --git a/docs/components/link.md b/docs/components/link.md
@@ -43,4 +43,4 @@ Specify the target attribute for the button link.
 
 ::: tip
 This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'a'>`.
-:::
+:::
diff --git a/docs/components/row.md b/docs/components/row.md
@@ -43,4 +43,4 @@ If `false`, instructs the component not to add default `style` properties to the
 
 ::: tip
 This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'table'>`.
-:::
+:::
diff --git a/docs/components/text.md b/docs/components/text.md
@@ -31,4 +31,4 @@ If `false`, instructs the component not to add default `style` properties to the
 
 ::: tip
 This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'p'>`.
-:::
+:::
diff --git a/docs/faq.md b/docs/faq.md
@@ -7,7 +7,10 @@ description: 'You know the drill. Questions that get asked oodles'
 
 ## Dark and Light Mode
 
-Handling dark and light mode in emails is tricky, and doesn't work exactly like one would expect with relevant experience handling modes on the web. There's a lot of information (and misinformation) out there about dark and light mode when authoring emails, but we recommend taking a look at the following article, which hits most of the important bits of info for authoring emails: https://www.litmus.com/blog/the-ultimate-guide-to-dark-mode-for-email-marketers
+Handling dark and light mode in emails is tricky, and doesn't work exactly like one would expect with relevant experience handling modes on the web. Gmail and Outlook on Windows in particular, have essentially no support for color switching. There's a lot of information (and misinformation) out there about dark and light mode when authoring emails, but we recommend taking a look at the following articles, which hit most of the important bits of info for authoring emails:
+
+- https://www.litmus.com/blog/the-ultimate-guide-to-dark-mode-for-email-marketers
+- https://web.dev/articles/color-scheme (crucial web development related dark mode info)
 
 ## Monorepo Setup
 

diff --git a/package.json b/package.json
@@ -41,7 +41,7 @@
     "*package.json": [
       "prettier --write --plugin=prettier-plugin-package"
     ],
-    "((.github/**/*)|(README|CHANGELOG)|(**/(README|CHANGELOG))).md": [
+    "((.github/**/*)|(docs/**/*)|(web/**/*.md)|(README|CHANGELOG)|(**/(README|CHANGELOG))).md": [
       "prettier --write"
     ]
   },

diff --git a/packages/jsx-email/src/components/color-scheme.tsx b/packages/jsx-email/src/components/color-scheme.tsx
@@ -0,0 +1,53 @@
+import type { JsxEmailComponent } from '../types';
+
+export type ColorSchemeMode =
+  | 'dark'
+  /**
+   * The email client will only ever render the content in the dark color scheme and forbids the
+   * email client from overriding the color scheme.
+   */
+  | 'dark only'
+  | 'light'
+  /**
+   * The email client will choose the light or dark theme to match the user’s preference.
+   * If the user’s preference does not match something in the list, the email client will choose
+   * which mode to display.
+   */
+  | 'light dark'
+  /**
+   * The email client will choose the first of the listed schemes that it supports taking user
+   * preference into account and forbids the email client from overriding the color scheme.
+   */
+  | 'light dark only'
+  /**
+   * The email client will only ever render the content in the light color scheme and forbids the
+   * email client from overriding the color scheme.
+   */
+  | 'light only'
+  /**
+   * Indicates that the email supports the page’s supported color schemes, if they are set, or
+   * that it supports no color schemes at all otherwise.
+   */
+  | 'normal';
+
+export interface ColorSchemeProps {
+  /**
+   * Selects the color scheme mode that informs the email client which mode to render.
+   * @default `normal`
+   */
+  mode?: ColorSchemeMode;
+}
+
+export const ColorScheme: JsxEmailComponent<ColorSchemeProps> = ({ mode = 'normal' }) => {
+  const style = `:root { color-scheme: ${mode}; supported-color-schemes: ${mode}; }`;
+
+  return (
+    <>
+      <meta name="color-scheme" content={mode} />
+      <meta name="supported-color-schemes" content={mode} />
+      <style dangerouslySetInnerHTML={{ __html: style }} />;
+    </>
+  );
+};
+
+ColorScheme.displayName = 'ColorScheme';
diff --git a/packages/jsx-email/src/index.ts b/packages/jsx-email/src/index.ts
@@ -1,6 +1,7 @@
 export * from './components/body';
 export * from './components/button/button';
 export * from './components/code';
+export * from './components/color-scheme';
 export * from './components/column';
 export * from './components/container';
 export * from './components/font';

diff --git a/packages/jsx-email/test/.snapshots/color-scheme.test.tsx.snap b/packages/jsx-email/test/.snapshots/color-scheme.test.tsx.snap
@@ -0,0 +1,15 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`<ColorScheme> component > renders correctly 1`] = `"<meta name=\\"color-scheme\\" content=\\"normal\\"/><meta name=\\"supported-color-schemes\\" content=\\"normal\\"/><style>:root { color-scheme: normal; supported-color-schemes: normal; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 2`] = `"<meta name=\\"color-scheme\\" content=\\"dark\\"/><meta name=\\"supported-color-schemes\\" content=\\"dark\\"/><style>:root { color-scheme: dark; supported-color-schemes: dark; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 3`] = `"<meta name=\\"color-scheme\\" content=\\"dark only\\"/><meta name=\\"supported-color-schemes\\" content=\\"dark only\\"/><style>:root { color-scheme: dark only; supported-color-schemes: dark only; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 4`] = `"<meta name=\\"color-scheme\\" content=\\"light\\"/><meta name=\\"supported-color-schemes\\" content=\\"light\\"/><style>:root { color-scheme: light; supported-color-schemes: light; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 5`] = `"<meta name=\\"color-scheme\\" content=\\"light dark\\"/><meta name=\\"supported-color-schemes\\" content=\\"light dark\\"/><style>:root { color-scheme: light dark; supported-color-schemes: light dark; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 6`] = `"<meta name=\\"color-scheme\\" content=\\"light dark only\\"/><meta name=\\"supported-color-schemes\\" content=\\"light dark only\\"/><style>:root { color-scheme: light dark only; supported-color-schemes: light dark only; }</style>;"`;
+
+exports[`<ColorScheme> component > renders correctly 7`] = `"<meta name=\\"color-scheme\\" content=\\"light only\\"/><meta name=\\"supported-color-schemes\\" content=\\"light only\\"/><style>:root { color-scheme: light only; supported-color-schemes: light only; }</style>;"`;
diff --git a/packages/jsx-email/test/color-scheme.test.tsx b/packages/jsx-email/test/color-scheme.test.tsx
@@ -0,0 +1,32 @@
+// @ts-ignore
+import React from 'react';
+
+import { jsxToString } from '../src/render';
+import { ColorScheme, type ColorSchemeMode } from '../src';
+
+describe('<ColorScheme> component', async () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+  });
+
+  it('renders correctly', async () => {
+    const html = await jsxToString(<ColorScheme />);
+    expect(html).toMatchSnapshot();
+
+    const modes: ColorSchemeMode[] = [
+      'dark',
+      'dark only',
+      'light',
+      'light dark',
+      'light dark only',
+      'light only'
+    ];
+
+    for (const mode of modes) {
+      // eslint-disable-next-line no-await-in-loop
+      const html = await jsxToString(<ColorScheme mode={mode} />);
+      expect(html).toMatchSnapshot();
+    }
+  });
+});
-Original file line number
+Diff line change
@@ Expand Up / @@ -43,4 +43,4 @@ Identify the direction of text content on the email @@
     :::tip
     This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'html'>`.
-    :::
+    :::
Original file line number	Diff line number	Diff line change
Expand Up		@@ -63,5 +63,3 @@ The width of an image in pixels
		::: tip
		This component also expresses all of the [Common Component Props](https://react.dev/reference/react-dom/components/common) for `ComponentProps<'img'>`.
		:::