Add email docs and stacks-email package

.prettierignore

@@ -1,6 +1,6 @@
 .vscode/
 dist/
-**/.svelte-kit
+.svelte-kit/
 # TODO: prettier breaks less files containing namespaced mixins with whitespaces
 # BEFORE PRETTIER: #stacks-internals #responsify('.w25', { width: 25% !important; });
 # AFTER PRETTIER:  #stacks-internals #responsify('.w25', { width: 25% !important; });;

packages/stacks-docs/README.md

@@ -161,3 +161,10 @@ The private docs follow the same structure and conventions as public docs. Mark
 3. **Add any images or assets** to the same directory as your markdown file
 
 4. **Reference assets** using relative paths (e.g., `./image.svg`) in your markdown
+
+## Email compile API auth (optional)
+
+`POST /api/email/compile` supports an optional shared Bearer token.
+
+- If `STACKS_EMAIL_AUTH_TOKEN` is not set: auth is disabled.
+- If `STACKS_EMAIL_AUTH_TOKEN` is set: the request must include `Authorization: Bearer <token>`.

packages/stacks-docs/_redirects

@@ -2,9 +2,6 @@
 https://alpha.stackoverflow.design/*             https://stackoverflow.design/:splat            301
 https://beta.stackoverflow.design/*              https://stackoverflow.design/:splat            302
 
-# Email section → v2 docs
-/email/*                                         https://v2.stackoverflow.design/email/:splat   302
-
 # Redirects from v2 urls
 /product                                        /system/develop/using-stacks/                   302
 /base/*                                         /system/base/:splat                             302

packages/stacks-docs/package.json

@@ -25,6 +25,7 @@
     "dependencies": {
         "@docsearch/css": "^4.3.2",
         "@docsearch/js": "^4.3.2",
+        "@stackoverflow/stacks-email": "*",
         "@hbsnow/rehype-sectionize": "^1.0.7",
         "@stackoverflow/stacks": "*",
         "@stackoverflow/stacks-editor": "*",

packages/stacks-docs/src/app.css

@@ -307,7 +307,7 @@ body {
 
 .ff-stack-sans-headline,
 .ff-stack-sans-headline-notch {
-    font-family: "Stack Sans Headline";
+    font-family: "Stack Sans Headline" !important;
 }
 .ff-stack-sans-headline-notch {
     font-feature-settings: "ss01" 1 !important;
@@ -550,6 +550,18 @@ h1 {
     padding: var(--su16);
 }
 
+/* Docs section card – used with a thumbnail to link to other areas in the docs i.e, for index pages */
+
+.docs-index-card {
+    border: var(--su1) solid var(--black-225);
+}
+.docs-index-card .docs-heading {
+    margin: 0 var(--su16) var(--su4);
+}
+.docs-index-card .docs-heading + p.docs-copy {
+    margin: 0 var(--su16) var(--su16);
+}
+
 /* Notices in doc content get breathing room below */
 .docs .s-notice {
     margin-bottom: var(--su16);

packages/stacks-docs/src/app.d.ts

@@ -1,5 +1,6 @@
 declare global {
     const __APP_VERSION__: string;
+    const __EMAIL_VERSION__: string;
     const __SVELTE_VERSION__: string;
 
     type DocsTocItem = {

packages/stacks-docs/src/components/EmailOptionsTable.svelte

@@ -0,0 +1,94 @@
+<script lang="ts">
+    import { onMount } from "svelte";
+
+    type ComponentOptionReference = {
+        argument: string;
+        type: string;
+        defaultValue?: string;
+        renderDefaultValueAsCode?: boolean;
+        description: string;
+    };
+
+    type EmailCatalogComponent = {
+        slug: string;
+        options?: ComponentOptionReference[];
+    };
+
+    type EmailCatalogResponse = {
+        catalog: {
+            components: EmailCatalogComponent[];
+            templates: EmailCatalogComponent[];
+        };
+    };
+
+    let {
+        rows = [],
+        componentSlug,
+        templateSlug,
+    }: {
+        rows?: ComponentOptionReference[];
+        componentSlug?: string;
+        templateSlug?: string;
+    } = $props();
+
+    let resolvedRows = $state<ComponentOptionReference[]>([]);
+
+    const hasDefaultValue = (value: string | undefined) =>
+        typeof value === "string" && value.trim().length > 0;
+
+    $effect(() => {
+        if (rows.length > 0) {
+            resolvedRows = rows;
+        }
+    });
+
+    onMount(async () => {
+        if ((!componentSlug && !templateSlug) || resolvedRows.length > 0) {
+            return;
+        }
+
+        const response = await fetch("/email/compiled/manifest.json");
+        if (!response.ok) {
+            return;
+        }
+
+        const manifest = (await response.json()) as EmailCatalogResponse;
+        const collection = componentSlug
+            ? manifest.catalog.components
+            : manifest.catalog.templates;
+        const slug = componentSlug ?? templateSlug;
+        const match = collection.find((item) => item.slug === slug);
+        resolvedRows = match?.options ?? [];
+    });
+</script>
+
+<div class="overflow-x-auto mb32">
+    <table class="docs-table s-table s-table__bx-simple">
+        <thead>
+            <tr>
+                <th class="s-table--cell2" scope="col">Argument</th>
+                <th class="s-table--cell3" scope="col">Type</th>
+                <th scope="col">Default</th>
+                <th scope="col">Description</th>
+            </tr>
+        </thead>
+        <tbody class="fs-caption">
+            {#each resolvedRows as row (row.argument)}
+                <tr>
+                    <td><code>{row.argument}</code></td>
+                    <td><code>{row.type}</code></td>
+                    <td>
+                        {#if hasDefaultValue(row.defaultValue)}
+                            {#if row.renderDefaultValueAsCode === false}
+                                {row.defaultValue}
+                            {:else}
+                                <code>{row.defaultValue}</code>
+                            {/if}
+                        {/if}
+                    </td>
+                    <td>{row.description}</td>
+                </tr>
+            {/each}
+        </tbody>
+    </table>
+</div>