Templates docs page (#194)

* feat minimal minimal template page

* Wire explore button

* Add templates to docs menu

* Add templates config file

* fix templates ssg

* add button icons

* add images fade

* responsive touches

* fix image props

* Update images

* lintfix

* fix build time image sizing

* add templates metadata

* Add download service usage

* add id headings for template page

* add pagingNav to template page

next.config.mjs

@@ -16,6 +16,11 @@ const nextConfig = {
         source: "/docs",
         destination: "/docs/installation",
         permanent: false
+      },
+      {
+        source: "/docs/templates",
+        destination: "/docs/templates/minimal",
+        permanent: false
       }
     ];
   },

src/app/(with-navbar)/(with-doc-nav)/docs/templates/[template]/page.tsx

@@ -0,0 +1,168 @@
+import { join } from "path";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import Image from "next/image";
+import { templates } from "@templates";
+import { PagingNav } from "@components/PagingNav";
+import { DocArticle, MdxH1, MdxH2, MdxP } from "@components/MdxComponents";
+import { DownloadIcon, OpenBlankIcon } from "@components/Icons";
+import { CTA } from "@components/CTA";
+import {
+  openGraphImageSize,
+  sharedOpenGraphMetadata,
+  flattenedDocsItems,
+} from "@constants";
+
+type TemplatePageProps = {
+  params: {
+    template: string;
+  };
+};
+
+const SERVICE_URL = "https://download-directory.github.io/?url=";
+const REPO_URL = "https://github.com/webscopeio/mailingui/tree/main/src/emails";
+
+function findPageTemplateItem(templateId: string) {
+  return templates.find((template) => template.id === templateId);
+}
+
+async function loadTemplate(templateId: string) {
+  const template = templates.find((t) => t.id === templateId);
+  if (!template) return null;
+  return template;
+}
+
+function getDownloadUrl(folder: string) {
+  return `${SERVICE_URL}${join(REPO_URL, folder)}`;
+}
+
+function findNeighbours(slug: string[]) {
+  const resolvedHref = ["/docs", ...slug].join("/");
+  const currentIndex = flattenedDocsItems.findIndex(
+    (item) => item.href === resolvedHref
+  );
+  const prev = currentIndex !== 0 ? flattenedDocsItems[currentIndex - 1] : null;
+  const next =
+    currentIndex !== flattenedDocsItems.length - 1
+      ? flattenedDocsItems[currentIndex + 1]
+      : null;
+  return {
+    prev,
+    next,
+  };
+}
+
+export function generateMetadata({ params }: TemplatePageProps): Metadata {
+  const doc = findPageTemplateItem(params.template);
+  const title = doc?.name ?? "Templates";
+  const description = doc?.description ?? "Explore templates";
+
+  return {
+    title,
+    description,
+    openGraph: {
+      ...sharedOpenGraphMetadata,
+      title,
+      description,
+      url: "https://mailingui.com/docs",
+      images: [
+        {
+          ...openGraphImageSize,
+          url: "/static/images/og/components.png",
+        },
+      ],
+    },
+  };
+}
+
+export default async function TemplatePage({ params }: TemplatePageProps) {
+  const template = await loadTemplate(params.template);
+  if (!template) notFound();
+
+  const { prev, next } = findNeighbours(["templates", params.template]);
+  return (
+    <div className="mx-auto w-full max-w-6xl overflow-hidden p-4 lg:py-0">
+      <DocArticle>
+        <div className="flex w-full flex-col gap-4 md:w-2/3 lg:w-1/2">
+          <MdxP className="mb-2">{template.shortDescription}</MdxP>
+          <MdxH1 id={`template-${template.id}`}>{template.name}</MdxH1>
+          <MdxP>{template.description}</MdxP>
+          <div className="grid grid-cols-2 gap-2">
+            <CTA color="white" className="grid place-content-center py-2">
+              <a href="#template-categories" className="h-full w-full">
+                Explore categories
+              </a>
+            </CTA>
+            <CTA
+              color="black"
+              href={getDownloadUrl(template.downloadFolder)}
+              target="_blank"
+            >
+              <DownloadIcon className="mr-2" />
+              Download all
+            </CTA>
+          </div>
+        </div>
+        <div className="w-full border-t border-neutral-800"></div>
+        <ul className="grid gap-16 py-4" id="template-categories">
+          {template.categories.map((category) => (
+            <li
+              key={category.name}
+              className="grid min-h-[16rem] gap-8 lg:grid-cols-[24rem_1fr] lg:gap-4"
+            >
+              <div className="flex flex-col gap-4">
+                <MdxH2 id={`template-${template.id}-${category.name}`}>
+                  {category.name}
+                </MdxH2>
+                <MdxP>{category.description}</MdxP>
+                <div className="grid max-w-[32rem] grid-cols-2 gap-2">
+                  {category.href && (
+                    <CTA
+                      color="white"
+                      className="w-full py-2"
+                      target="_blank"
+                      href={category.href}
+                    >
+                      <OpenBlankIcon className="mr-2" />
+                      See preview
+                    </CTA>
+                  )}
+                  <CTA
+                    color="black"
+                    className="w-full py-2"
+                    href={getDownloadUrl(category.downloadFolder)}
+                    target="_blank"
+                  >
+                    <DownloadIcon className="mr-2" />
+                    Download
+                  </CTA>
+                </div>
+              </div>
+              <div className="overflow-x-scroll">
+                <div className="relative flex w-max gap-4">
+                  {category.imageUrl.map((url, i) => (
+                    <Image
+                      key={i}
+                      src={url}
+                      height={232}
+                      width={260}
+                      alt={`Minimal - ${category.name} image preview`}
+                      className="rounded-md"
+                    ></Image>
+                  ))}
+                  <div className="absolute bottom-0 h-1/2 w-full bg-[linear-gradient(to_bottom,transparent,#000000)]" />
+                </div>
+              </div>
+            </li>
+          ))}
+        </ul>
+      </DocArticle>
+      <PagingNav prev={prev} next={next} className="mt-8" />
+    </div>
+  );
+}
+
+export const generateStaticParams = () =>
+  templates.map((template) => ({
+    template: template.id,
+  }));

src/docs/components/Icons/DownloadIcon.tsx

@@ -0,0 +1,17 @@
+import { IconProps } from "./types";
+
+export const DownloadIcon = ({ ...delegated }: IconProps) => (
+  <svg
+    viewBox="0 0 24 24"
+    stroke="currentColor"
+    width="1.25rem"
+    height="1.25rem"
+    {...delegated}
+  >
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M3 16.5v2.25A2.25 2.25 0 005.25 21h13.5A2.25 2.25 0 0021 18.75V16.5M16.5 12L12 16.5m0 0L7.5 12m4.5 4.5V3"
+    />
+  </svg>
+);

src/docs/components/Icons/OpenBlankIcon.tsx

@@ -0,0 +1,18 @@
+import { IconProps } from "./types";
+
+export const OpenBlankIcon = ({ ...delegated }: IconProps) => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    width="1.25rem"
+    height="1.25rem"
+    {...delegated}
+  >
+    <path
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      d="M13.5 6H5.25A2.25 2.25 0 003 8.25v10.5A2.25 2.25 0 005.25 21h10.5A2.25 2.25 0 0018 18.75V10.5m-10.5 6L21 3m0 0h-5.25M21 3v5.25"
+    />
+  </svg>
+);

src/docs/components/Icons/index.ts

@@ -4,6 +4,7 @@ export { CodeIcon } from "./CodeIcon";
 export { CopyIcon } from "./CopyIcon";
 export { CrossIcon } from "./CrossIcon";
 export { DesktopIcon } from "./DesktopIcon";
+export { DownloadIcon } from "./DownloadIcon";
 export { EyeIcon } from "./EyeIcon";
 export { GitHubIcon } from "./GitHubIcon";
 export { ChevronDownIcon } from "./ChevronDownIcon";
@@ -12,6 +13,7 @@ export { ChevronRightIcon } from "./ChevronRightIcon";
 export { HtmlIcon } from "./HtmlIcon";
 export { LibraryIcon } from "./LibraryIcon";
 export { MenuIcon } from "./MenuIcon";
+export { OpenBlankIcon } from "./OpenBlankIcon";
 export { ReactIcon } from "./ReactIcon";
 export { ShareIcon } from "./ShareIcon";
 export { SunIcon } from "./SunIcon";

src/docs/constants/docsItems.ts

@@ -1,4 +1,5 @@
 import { componentTypes } from "@examples";
+import { templates } from "@templates";
 
 export type DocItems = DocItemGroup[];
 export type DocItemGroup = {
@@ -39,6 +40,14 @@ export const docsItems: DocItems = [
         .sort((a, b) => a.label.localeCompare(b.label)),
     ],
   },
+  {
+    label: "Templates",
+    items: templates.map((template) => ({
+      href: `/docs/templates/${template.id}`,
+      label: template.name,
+      description: template.shortDescription,
+    })),
+  },
 ];
 
 export const flattenedDocsItems = docsItems.reduce((acc, item) => {

src/docs/templates/index.ts

@@ -0,0 +1,52 @@
+import type { Template } from "./types";
+
+export type { Template };
+
+export const templates: Template[] = [
+  {
+    id: "minimal",
+    name: "Minimal",
+    shortDescription: "Free email template",
+    description:
+      "Minimal is a simple and clean email template. It comes with three different email categories.",
+    downloadFolder: "",
+    categories: [
+      {
+        name: "Events",
+        description:
+          "Events are a great way to get people together. Can be conference, a meetup, or a party.",
+        href: "/preview/events",
+        imageUrl: [
+          "/static/images/templates-docs/events-1.png",
+          "/static/images/templates-docs/events-2.png",
+          "/static/images/templates-docs/events-3.png",
+        ],
+        downloadFolder: "events",
+      },
+      {
+        name: "Marketing",
+        description:
+          "Marketing emails are a great way to promote your business with product announcement or a special offer.",
+        href: "/preview/marketing",
+        imageUrl: [
+          "/static/images/templates-docs/marketing-1.png",
+          "/static/images/templates-docs/marketing-2.png",
+          "/static/images/templates-docs/marketing-3.png",
+        ],
+        downloadFolder: "marketing",
+      },
+      {
+        name: "Newsletter",
+        description:
+          "Newsletters are a great way to keep your audience up-to-date with what's going on in your business.",
+        href: "/preview/newsletter",
+        imageUrl: [
+          "/static/images/templates-docs/newsletter-1.png",
+          "/static/images/templates-docs/newsletter-2.png",
+          "/static/images/templates-docs/newsletter-3.png",
+        ],
+        downloadFolder: "newsletter",
+      },
+    ],
+  },
+];

src/docs/templates/types.ts

@@ -0,0 +1,16 @@
+export type Template = {
+  id: string;
+  name: string;
+  shortDescription: string;
+  description: string;
+  categories: TemplateCategory[];
+  downloadFolder: string;
+};
+
+type TemplateCategory = {
+  name: string;
+  description: string;
+  imageUrl: string[];
+  href: string;
+  downloadFolder: string;
+};

tsconfig.json

@@ -28,6 +28,7 @@
       "@utils/*": ["./src/docs/utils/*"],
       "@examples": ["./src/docs/examples/index.ts"],
       "@examples/*": ["./src/docs/examples/*"],
+      "@templates": ["./src/docs/templates/index.ts"],
       "@mailingui/components": ["src/mailingui/components/index.ts"],
       "@mailingui/types": ["src/mailingui/types/index.ts"],
       "@mailingui/themes": ["src/mailingui/themes/index.ts"]