@sandboxsonny/ace-kit 0.4.0 → 0.6.0

package/templates/astro/src/components/PageContent.astro

@@ -0,0 +1,113 @@
+---
+import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+import AceLink from "@sandboxsonny/ace-kit/astro/AceLink.astro";
+import AceRichText from "@sandboxsonny/ace-kit/astro/AceRichText.astro";
+import AceTextArea from "@sandboxsonny/ace-kit/astro/AceTextArea.astro";
+import { formatAceDate } from "@sandboxsonny/ace-kit";
+import type { AceEntry } from "@sandboxsonny/ace-kit";
+
+import AceSections from "@sandboxsonny/ace-kit/astro/AceSections.astro";
+
+import Faq from "~/components/sections/Faq.astro";
+import Gallery from "~/components/sections/Gallery.astro";
+import Hero from "~/components/sections/Hero.astro";
+
+import type { PageValues } from "~/types/page";
+
+type Props = {
+  entry: AceEntry<PageValues>;
+};
+
+const { entry } = Astro.props;
+const { headline, body, hero, published, button, content } = entry.values;
+---
+
+<section class="section">
+  <div class="container prose">
+    <h1>{headline || entry.title}</h1>
+    {entry.description && <p class="intro">{entry.description}</p>}
+    {
+      // A date field is a day with no time of day, so it is the same day wherever the server runs.
+      published && (
+        <p class="published">
+          Published <time datetime={published}>{formatAceDate(published, { locale: "en-GB" }) ?? published}</time>
+        </p>
+      )
+    }
+    {hero && (
+      <figure>
+        <AceImage image={hero} sizes="(min-width: 64rem) 64rem, 100vw" lazy={false} />
+      </figure>
+    )}
+    {
+      // A site made before its Body field was rich text still has plain text, with blank lines between paragraphs.
+      typeof body === "string" ? (
+        <AceTextArea value={body} />
+      ) : body ? (
+        <div class="rich-text">
+          <AceRichText document={body} />
+        </div>
+      ) : null
+    }
+    {
+      // A link field: the editor's words and where it goes, already worked out by the CMS.
+      button && (
+        <p class="actions">
+          <AceLink link={button} class="button" />
+        </p>
+      )
+    }
+  </div>
+</section>
+<AceSections sections={content} components={{ hero: Hero, faq: Faq, gallery: Gallery }} />
+<style>
+  .prose {
+    max-width: 42rem;
+  }
+  .intro {
+    color: var(--colour-muted);
+    font-size: 1.125rem;
+  }
+  .published {
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+  .actions {
+    margin-top: 2rem;
+  }
+  figure {
+    margin: 2rem 0;
+  }
+  figure :global(img) {
+    border-radius: 0.5rem;
+  }
+  .rich-text :global(* + *) {
+    margin-top: 1rem;
+  }
+  .rich-text :global(h2) {
+    font-size: 1.75rem;
+  }
+  .rich-text :global(h3) {
+    font-size: 1.4rem;
+  }
+  .rich-text :global(h4) {
+    font-size: 1.15rem;
+  }
+  .rich-text :global(ul) {
+    list-style: disc;
+    padding-left: 1.5rem;
+  }
+  .rich-text :global(ol) {
+    list-style: decimal;
+    padding-left: 1.5rem;
+  }
+  .rich-text :global(blockquote) {
+    border-left: 4px solid var(--colour-muted);
+    padding-left: 1rem;
+    font-style: italic;
+  }
+  .rich-text :global(img) {
+    max-width: 100%;
+    height: auto;
+  }
+</style>

package/templates/astro/src/components/SiteFooter.astro

@@ -0,0 +1,19 @@
+---
+const year = new Date().getFullYear();
+---
+
+<footer class="site-footer">
+  <div class="container">
+    <p>© {year} Example Site. A test site for CMS Ace.</p>
+  </div>
+</footer>
+
+<style>
+  .site-footer {
+    margin-top: 3rem;
+    padding-block: 2rem;
+    background: var(--colour-surface);
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+</style>

package/templates/astro/src/components/SiteHeader.astro

@@ -0,0 +1,121 @@
+---
+import { isCurrentPage } from "@sandboxsonny/ace-kit";
+import { getMenuLinks } from "@sandboxsonny/ace-kit/astro";
+
+// The CMS menu with the handle "main-menu", or the built-in links if the site has none yet or the CMS can't be reached.
+const links = await getMenuLinks("main-menu", {
+  fallback: [
+    { label: "Home", to: "/" },
+    { label: "About", to: "/pages/about" },
+    { label: "Contact", to: "/pages/contact" },
+  ],
+});
+const { pathname } = Astro.url;
+---
+
+<header class="site-header">
+  <div class="container site-header__inner">
+    <a href="/" class="site-header__name">
+      Example Site
+    </a>
+    <nav aria-label="Main">
+      <ul class="site-header__links">
+        {links.map((link) => (
+          <li>
+            <a href={link.to} aria-current={isCurrentPage(link, pathname) ? "page" : undefined}>
+              {link.label}
+            </a>
+            {link.children && link.children.length > 0 && (
+              <ul class="site-header__sublinks">
+                {link.children.map((child) => (
+                  <li>
+                    <a href={child.to} aria-current={isCurrentPage(child, pathname) ? "page" : undefined}>
+                      {child.label}
+                    </a>
+                    {child.children && child.children.length > 0 && (
+                      <ul class="site-header__sublinks site-header__sublinks--deep">
+                        {child.children.map((grandchild) => (
+                          <li>
+                            <a href={grandchild.to}>{grandchild.label}</a>
+                          </li>
+                        ))}
+                      </ul>
+                    )}
+                  </li>
+                ))}
+              </ul>
+            )}
+          </li>
+        ))}
+      </ul>
+    </nav>
+  </div>
+</header>
+
+<style>
+  .site-header {
+    border-bottom: 1px solid var(--colour-surface);
+  }
+  .site-header__inner {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding-block: 1rem;
+  }
+  .site-header__name {
+    font-weight: 700;
+    font-size: 1.25rem;
+    color: var(--colour-text);
+    text-decoration: none;
+  }
+  .site-header__links {
+    display: flex;
+    gap: 1.5rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .site-header__links a {
+    color: var(--colour-muted);
+    text-decoration: none;
+  }
+  .site-header__links > li {
+    position: relative;
+  }
+  .site-header__sublinks {
+    display: none;
+    position: absolute;
+    z-index: 10;
+    top: 100%;
+    left: 0;
+    min-width: 12rem;
+    margin: 0;
+    padding: 0.5rem 0;
+    list-style: none;
+    background: var(--colour-background);
+    border: 1px solid var(--colour-surface);
+    border-radius: 0.5rem;
+  }
+  .site-header__sublinks li {
+    position: relative;
+  }
+  .site-header__sublinks a {
+    display: block;
+    padding: 0.4rem 1rem;
+    white-space: nowrap;
+  }
+  .site-header__sublinks--deep {
+    top: 0;
+    left: 100%;
+  }
+  .site-header__links > li:hover > .site-header__sublinks,
+  .site-header__links > li:focus-within > .site-header__sublinks,
+  .site-header__sublinks li:hover > .site-header__sublinks,
+  .site-header__sublinks li:focus-within > .site-header__sublinks {
+    display: block;
+  }
+  .site-header__links a[aria-current="page"] {
+    color: var(--colour-text);
+    font-weight: 600;
+  }
+</style>

package/templates/astro/src/components/sections/Faq.astro

@@ -0,0 +1,54 @@
+---
+import AceRichText from "@sandboxsonny/ace-kit/astro/AceRichText.astro";
+
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import type faq from "./Faq.schema";
+
+type Props = {
+  section: SectionOf<typeof faq>;
+};
+
+const { section } = Astro.props;
+const { heading } = section.values;
+---
+
+<section class="section" data-section={section.type}>
+  <div class="container faq">
+    {heading && <h2>{heading}</h2>}
+    {section.blocks.map((block) => (
+      <details>
+        <summary>{block.values.question}</summary>
+        {block.values.answer && (
+          <div class="answer">
+            <AceRichText document={block.values.answer} />
+          </div>
+        )}
+      </details>
+    ))}
+  </div>
+</section>
+
+<style>
+  .faq {
+    max-width: 42rem;
+  }
+  h2 {
+    margin: 0 0 1rem;
+    font-size: 1.75rem;
+  }
+  details {
+    border-bottom: 1px solid var(--colour-surface);
+    padding-block: 0.75rem;
+  }
+  summary {
+    cursor: pointer;
+    font-weight: 600;
+  }
+  .answer {
+    margin-top: 0.5rem;
+    color: var(--colour-muted);
+  }
+  .answer :global(* + *) {
+    margin-top: 0.75rem;
+  }
+</style>

package/templates/astro/src/components/sections/Faq.schema.ts

@@ -0,0 +1,17 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// An FAQ is a heading and a list of questions. The questions are blocks: the editor adds as many as they like.
+export default defineSection({
+  handle: "faq",
+  name: "FAQ",
+  fields: [{ handle: "heading", label: "Heading", type: "text" }],
+  blocks: {
+    question: {
+      name: "Question",
+      fields: [
+        { handle: "question", label: "Question", type: "text", required: true },
+        { handle: "answer", label: "Answer", type: "richtext" },
+      ],
+    },
+  },
+});

package/templates/astro/src/components/sections/Gallery.astro

@@ -0,0 +1,74 @@
+---
+import { formatAceDate } from "@sandboxsonny/ace-kit";
+import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import type gallery from "./Gallery.schema";
+
+type Props = {
+  section: SectionOf<typeof gallery>;
+};
+
+const { section } = Astro.props;
+const { heading, published } = section.values;
+const photos = section.blocks.filter((block) => block.values.image || block.values.caption);
+---
+
+<section class="section" data-section={section.type}>
+  <div class="container">
+    {heading && <h2>{heading}</h2>}
+    {published && (
+      <p class="published">
+        <time datetime={published}>{formatAceDate(published, { locale: "en-GB" }) ?? published}</time>
+      </p>
+    )}
+    {photos.length > 0 ? (
+      <ul class="photos">
+        {photos.map((photo) => (
+          <li>
+            <figure>
+              {photo.values.image && <AceImage image={photo.values.image} sizes="(min-width: 48rem) 20rem, 100vw" />}
+              {photo.values.caption && <figcaption>{photo.values.caption}</figcaption>}
+            </figure>
+          </li>
+        ))}
+      </ul>
+    ) : (
+      <p class="empty">No photos yet.</p>
+    )}
+  </div>
+</section>
+
+<style>
+  h2 {
+    margin: 0 0 0.25rem;
+    font-size: 1.75rem;
+  }
+  .published,
+  .empty {
+    margin: 0 0 1rem;
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+  .photos {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(14rem, 1fr));
+    gap: 1rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  figure {
+    margin: 0;
+  }
+  figure :global(img) {
+    border-radius: 0.5rem;
+    width: 100%;
+    object-fit: cover;
+  }
+  figcaption {
+    margin-top: 0.4rem;
+    color: var(--colour-muted);
+    font-size: 0.9rem;
+  }
+</style>

package/templates/astro/src/components/sections/Gallery.schema.ts

@@ -0,0 +1,20 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// A gallery is a heading, a date and a list of photos. The photos are blocks.
+export default defineSection({
+  handle: "gallery",
+  name: "Gallery",
+  fields: [
+    { handle: "heading", label: "Heading", type: "text" },
+    { handle: "published", label: "Published", type: "date" },
+  ],
+  blocks: {
+    photo: {
+      name: "Photo",
+      fields: [
+        { handle: "image", label: "Image", type: "image" },
+        { handle: "caption", label: "Caption", type: "text" },
+      ],
+    },
+  },
+});

package/templates/astro/src/components/sections/Hero.astro

@@ -0,0 +1,58 @@
+---
+import AceImage from "@sandboxsonny/ace-kit/astro/AceImage.astro";
+import AceLink from "@sandboxsonny/ace-kit/astro/AceLink.astro";
+
+import type { SectionOf } from "@sandboxsonny/ace-kit";
+import type hero from "./Hero.schema";
+
+type Props = {
+  section: SectionOf<typeof hero>;
+};
+
+const { section } = Astro.props;
+const { heading, subheading, picture, button } = section.values;
+---
+
+<section class="hero section--surface" data-section={section.type}>
+  <div class="container hero__inner">
+    <div class="hero__text">
+      <h2>{heading}</h2>
+      {subheading && <p class="hero__subheading">{subheading}</p>}
+      {button && <AceLink link={button} class="button" />}
+    </div>
+    {picture && (
+      <div class="hero__picture">
+        <AceImage image={picture} sizes="(min-width: 64rem) 32rem, 100vw" lazy={false} />
+      </div>
+    )}
+  </div>
+</section>
+
+<style>
+  .hero {
+    padding-block: 3rem;
+  }
+  .hero__inner {
+    display: grid;
+    gap: 2rem;
+    align-items: center;
+  }
+  @media (min-width: 48rem) {
+    .hero__inner:has(.hero__picture) {
+      grid-template-columns: 1fr 1fr;
+    }
+  }
+  h2 {
+    margin: 0 0 0.75rem;
+    font-size: 2.25rem;
+    line-height: 1.15;
+  }
+  .hero__subheading {
+    margin: 0 0 1.5rem;
+    color: var(--colour-muted);
+    font-size: 1.15rem;
+  }
+  .hero__picture :global(img) {
+    border-radius: 0.5rem;
+  }
+</style>

package/templates/astro/src/components/sections/Hero.schema.ts

@@ -0,0 +1,14 @@
+import { defineSection } from "@sandboxsonny/ace-kit";
+
+// What a hero can hold. The CMS learns it from this file (the dev server syncs it when it changes), and Hero.astro's
+// props are typed from it.
+export default defineSection({
+  handle: "hero",
+  name: "Hero",
+  fields: [
+    { handle: "heading", label: "Heading", type: "text", required: true },
+    { handle: "subheading", label: "Subheading", type: "textarea" },
+    { handle: "picture", label: "Picture", type: "image" },
+    { handle: "button", label: "Button", type: "link" },
+  ],
+});

package/templates/astro/src/layouts/BaseLayout.astro

@@ -0,0 +1,36 @@
+---
+import AcePreviewRefresh from "@sandboxsonny/ace-kit/astro/AcePreviewRefresh.astro";
+import SiteFooter from "~/components/SiteFooter.astro";
+import SiteHeader from "~/components/SiteHeader.astro";
+import "~/styles/global.css";
+
+type Props = {
+  title: string;
+  description?: string;
+  /** True when the page is showing a draft inside the CMS's preview frame. */
+  preview?: boolean;
+};
+
+const { title, description = "A simple example site for testing CMS Ace.", preview = false } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content={description} />
+    <meta name="generator" content={Astro.generator} />
+    {preview && <meta name="robots" content="noindex" />}
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>{title}</title>
+  </head>
+  <body>
+    <SiteHeader />
+    <main>
+      <slot />
+    </main>
+    <SiteFooter />
+    <AcePreviewRefresh />
+  </body>
+</html>

package/templates/astro/src/pages/[...slug].astro

@@ -0,0 +1,31 @@
+---
+import { getPage } from "@sandboxsonny/ace-kit/astro";
+import AceNotice from "@sandboxsonny/ace-kit/astro/AceNotice.astro";
+
+import PageContent from "~/components/PageContent.astro";
+import BaseLayout from "~/layouts/BaseLayout.astro";
+import type { PageValues } from "~/types/page";
+
+// Addresses are /{content type}/{entry}, as on Shopify: "/pages/about" is the entry "about" of the content type
+// "pages", and "/" is the home entry. getPage works out what to show and sets the status and headers.
+const page = await getPage<PageValues>(Astro);
+if (page.kind === "redirect") return Astro.redirect(page.location, page.status);
+
+const isPreview = Boolean(page.headers["Cache-Control"]);
+---
+
+{page.kind === "entry" ? (
+  <BaseLayout
+    title={`${page.entry.title} | Example Site`}
+    description={page.entry.description || undefined}
+    preview={isPreview}
+  >
+    <PageContent entry={page.entry} />
+  </BaseLayout>
+) : (
+  <BaseLayout title="Example Site" preview={isPreview}>
+    <section class="section">
+      <AceNotice page={page} class="container" />
+    </section>
+  </BaseLayout>
+)}

package/templates/astro/src/styles/global.css

@@ -0,0 +1,56 @@
+:root {
+  --colour-background: #ffffff;
+  --colour-surface: #f4f6f8;
+  --colour-text: #1b2430;
+  --colour-muted: #5b6776;
+  --colour-accent: #2f5bea;
+  --colour-accent-text: #ffffff;
+  --content-width: 64rem;
+  --font-body: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: var(--font-body);
+  line-height: 1.6;
+  color: var(--colour-text);
+  background: var(--colour-background);
+}
+
+img {
+  max-width: 100%;
+  height: auto;
+}
+
+a {
+  color: var(--colour-accent);
+}
+
+.container {
+  width: min(100% - 2rem, var(--content-width));
+  margin-inline: auto;
+}
+
+.button {
+  display: inline-block;
+  padding: 0.75rem 1.25rem;
+  border-radius: 0.5rem;
+  background: var(--colour-accent);
+  color: var(--colour-accent-text);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.section {
+  padding-block: 3rem;
+}
+
+.section--surface {
+  background: var(--colour-surface);
+}

package/templates/astro/src/types/page.d.ts

@@ -0,0 +1,4 @@
+import type { AceContentTypes } from "@sandboxsonny/ace-kit";
+
+/** The fields of the "Pages" content type, as generated from the CMS (see `npm run generate`). */
+export type PageValues = AceContentTypes["pages"];

package/templates/astro/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"],
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["src/*"]
+    }
+  }
+}

package/templates/astro/vitest.config.ts

@@ -0,0 +1,4 @@
+/// <reference types="vitest/config" />
+import { getViteConfig } from "astro/config";
+
+export default getViteConfig({ test: { include: ["src/**/*.test.ts"] } });