create-shapio 0.2.0

package/templates/next/src/app/[locale]/articles/page.tsx

@@ -0,0 +1,28 @@
+import type { Metadata } from 'next';
+import { ArticleCard } from '../../../components/ArticleCard';
+import { listArticles } from '../../../lib/shapio';
+import { stringsFor, toLocale } from '../../../lib/site';
+
+type ArticlesParams = { params: Promise<{ locale: string }> };
+
+export const generateMetadata = async ({ params }: ArticlesParams): Promise<Metadata> => ({
+  title: stringsFor(toLocale((await params).locale)).articles,
+});
+
+const ArticlesPage = async ({ params }: ArticlesParams) => {
+  const locale = toLocale((await params).locale);
+  const strings = stringsFor(locale);
+  const articles = await listArticles(locale);
+  return (
+    <>
+      <h1 className="page-title">{strings.articles}</h1>
+      <ul className="cards">
+        {articles.map((article) => (
+          <ArticleCard key={article.id} article={article} locale={locale} strings={strings} />
+        ))}
+      </ul>
+    </>
+  );
+};
+
+export default ArticlesPage;

package/templates/next/src/app/[locale]/colophon/page.tsx

@@ -0,0 +1,25 @@
+import type { Metadata } from 'next';
+import { RichText } from '../../../components/RichText';
+import { getSiteSettings } from '../../../lib/shapio';
+import { stringsFor, toLocale } from '../../../lib/site';
+
+type ColophonParams = { params: Promise<{ locale: string }> };
+
+export const generateMetadata = async ({ params }: ColophonParams): Promise<Metadata> => ({
+  title: stringsFor(toLocale((await params).locale)).colophon,
+});
+
+/** The singleton page: the siteSettings entry's colophon, one per locale. */
+const ColophonPage = async ({ params }: ColophonParams) => {
+  const locale = toLocale((await params).locale);
+  const settings = await getSiteSettings(locale);
+  return (
+    <>
+      <h1 className="page-title">{stringsFor(locale).colophon}</h1>
+      {settings?.tagline ? <p className="lead">{settings.tagline}</p> : null}
+      <RichText value={settings?.colophon ?? null} />
+    </>
+  );
+};
+
+export default ColophonPage;

package/templates/next/src/app/[locale]/layout.tsx

@@ -0,0 +1,77 @@
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import { notFound } from 'next/navigation';
+import type { ReactNode } from 'react';
+import { LocaleSwitch } from '../../components/LocaleSwitch';
+import { getSiteSettings } from '../../lib/shapio';
+import {
+  articlesPath,
+  colophonPath,
+  HOME_SLUG,
+  isLocale,
+  LOCALES,
+  otherLocale,
+  pagePath,
+  stringsFor,
+  toLocale,
+} from '../../lib/site';
+import '../site.css';
+
+/**
+ * Only the site's locales exist; any other first segment is a 404 (notFound below). Not `dynamicParams = false`:
+ * Next answers a page that /api/revalidate marked stale with a 404 when its route allows no fallback, so every
+ * route here renders on demand and rejects unknown values itself.
+ */
+export const dynamicParams = true;
+export const generateStaticParams = () => LOCALES.map((locale) => ({ locale }));
+
+type LocaleParams = { params: Promise<{ locale: string }> };
+
+export const generateMetadata = async ({ params }: LocaleParams): Promise<Metadata> => {
+  const locale = toLocale((await params).locale);
+  const siteName = (await getSiteSettings(locale))?.siteName ?? stringsFor(locale).siteName;
+  return { title: { template: `%s · ${siteName}`, default: siteName }, icons: '/favicon.svg' };
+};
+
+type LocaleLayoutProps = LocaleParams & { children: ReactNode };
+
+/** The root layout: every page lives under its locale (`/en/…`, `/fr/…`). */
+const LocaleLayout = async ({ children, params }: LocaleLayoutProps) => {
+  const segment = (await params).locale;
+  if (!isLocale(segment)) {
+    notFound();
+  }
+  const locale = toLocale(segment);
+  const strings = stringsFor(locale);
+  // The name, tagline and footer come from the siteSettings singleton (built-in strings until it is published).
+  const settings = await getSiteSettings(locale);
+  const other = otherLocale(locale);
+  return (
+    <html lang={locale}>
+      <body>
+        <a className="skip" href="#content">
+          {strings.skipToContent}
+        </a>
+        <header className="site-header">
+          <Link className="brand" href={pagePath(locale, HOME_SLUG)}>
+            {settings?.siteName ?? strings.siteName}
+          </Link>
+          {settings?.tagline ? <p className="tagline">{settings.tagline}</p> : null}
+          <nav aria-label="Main">
+            <Link href={articlesPath(locale)}>{strings.articles}</Link>
+            <Link href={colophonPath(locale)}>{strings.colophon}</Link>
+            <LocaleSwitch to={other} label={strings.switchTo} />
+          </nav>
+        </header>
+        <main id="content">{children}</main>
+        <footer className="site-footer">
+          <p>
+            {settings?.siteName ?? strings.siteName} · {settings?.footer ?? strings.footer} · Next.js
+          </p>
+        </footer>
+      </body>
+    </html>
+  );
+};
+
+export default LocaleLayout;

package/templates/next/src/app/api/revalidate/route.ts

@@ -0,0 +1,31 @@
+import { webhookSecret } from '../../../lib/config';
+import { log } from '../../../lib/log';
+import { revalidateChanges } from '../../../lib/revalidation';
+import { REVALIDATING_EVENTS } from '../../../lib/revalidationTargets';
+import { readWebhookEvent } from '../../../lib/webhookEvent';
+
+/**
+ * POST /api/revalidate/ (with the slash: `trailingSlash` redirects the other form, and Shapio's webhooks do not
+ * follow redirects): the target of the Shapio webhook the seed creates (publish, unpublish, delete,
+ * change set shipped, schema change). A signed delivery refreshes the pages whose content changed since the
+ * snapshot the site shows (src/lib/revalidation.ts). A failure answers 500, so Shapio retries the delivery.
+ */
+export const POST = async (request: Request) => {
+  const read = await readWebhookEvent(request, webhookSecret());
+  if (!read.ok) {
+    log(`Refused a webhook delivery: ${read.reason}`);
+    return Response.json({ error: read.reason }, { status: read.status });
+  }
+  const { event } = read;
+  if (!REVALIDATING_EVENTS.includes(event.type)) {
+    return Response.json({ event: event.type, ignored: true });
+  }
+  try {
+    return Response.json({ event: event.type, ...(await revalidateChanges()) });
+  } catch (error) {
+    log(
+      `Revalidation for ${event.type} ${event.id} failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return Response.json({ error: 'revalidation failed' }, { status: 500 });
+  }
+};

package/templates/next/src/app/preview/layout.tsx

@@ -0,0 +1,20 @@
+import type { Metadata } from 'next';
+import type { ReactNode } from 'react';
+import '../site.css';
+
+/** Drafts are never indexed, and the token in the URL is never sent on as a Referer. */
+export const metadata: Metadata = {
+  title: 'Preview',
+  robots: { index: false, follow: false },
+  referrer: 'no-referrer',
+  icons: '/favicon.svg',
+};
+
+/** The preview's own root layout (outside `[locale]`): the draft renders client-side with the token. */
+const PreviewLayout = ({ children }: { children: ReactNode }) => (
+  <html lang="en">
+    <body>{children}</body>
+  </html>
+);
+
+export default PreviewLayout;

package/templates/next/src/app/preview/page.tsx

@@ -0,0 +1,6 @@
+import { Preview } from '../../components/Preview';
+
+/** `/preview/`: the draft Shapio's preview URL points at (see src/lib/preview.ts). */
+const PreviewPage = () => <Preview />;
+
+export default PreviewPage;

package/templates/next/src/app/site.css

@@ -0,0 +1,199 @@
+/* The example site's whole stylesheet: system fonts, the Shapio palette, light and dark. */
+:root {
+  --ink: #0f172a;
+  --ivory: #faf9f6;
+  --cobalt: #2563eb;
+  --periwinkle: #a5b4fc;
+  --muted: #475569;
+  --surface: #ffffff;
+  --border: #e2e8f0;
+  color-scheme: light dark;
+  font-family:
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    Roboto,
+    sans-serif;
+  line-height: 1.6;
+  color: var(--ink);
+  background: var(--ivory);
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --ink: #e2e8f0;
+    --ivory: #0f172a;
+    --cobalt: #a5b4fc;
+    --muted: #94a3b8;
+    --surface: #1e293b;
+    --border: #334155;
+  }
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+}
+img {
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+a {
+  color: var(--cobalt);
+}
+.skip {
+  position: absolute;
+  left: -999px;
+}
+.skip:focus {
+  left: 1rem;
+  top: 1rem;
+  background: var(--surface);
+  padding: 0.5rem;
+}
+.site-header,
+.site-footer,
+main {
+  max-width: 64rem;
+  margin: 0 auto;
+  padding: 1rem;
+}
+.site-header {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  align-items: center;
+  justify-content: space-between;
+}
+.site-header nav {
+  display: flex;
+  gap: 1rem;
+}
+.brand {
+  font-weight: 800;
+  text-decoration: none;
+  color: inherit;
+  font-size: 1.25rem;
+}
+.tagline {
+  flex: 1;
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.875rem;
+}
+.site-footer {
+  color: var(--muted);
+  font-size: 0.875rem;
+  border-top: 1px solid var(--border);
+}
+.button {
+  display: inline-block;
+  background: var(--cobalt);
+  color: var(--ivory);
+  padding: 0.75rem 1.25rem;
+  border-radius: 0.5rem;
+  text-decoration: none;
+  font-weight: 600;
+}
+.hero {
+  display: grid;
+  gap: 2rem;
+  align-items: center;
+  padding: 2rem 0;
+}
+@media (min-width: 64rem) {
+  .hero {
+    grid-template-columns: 1fr 1fr;
+  }
+}
+.hero h1 {
+  font-size: clamp(2rem, 5vw, 3.25rem);
+  line-height: 1.1;
+  margin: 0 0 1rem;
+}
+.lead {
+  font-size: 1.25rem;
+  color: var(--muted);
+}
+.hero-image,
+.cover {
+  border-radius: 0.75rem;
+}
+.feature-grid,
+.gallery-grid,
+.cards {
+  list-style: none;
+  padding: 0;
+  display: grid;
+  gap: 1.5rem;
+  grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+}
+.feature-grid li,
+.card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 0.75rem;
+  padding: 1.25rem;
+}
+.gallery figure {
+  margin: 0;
+}
+.gallery img {
+  border-radius: 0.5rem;
+  aspect-ratio: 4 / 3;
+  object-fit: cover;
+  width: 100%;
+}
+.cta {
+  text-align: center;
+  padding: 3rem 1rem;
+  background: var(--surface);
+  border-radius: 1rem;
+  margin: 2rem 0;
+}
+.article {
+  max-width: 48rem;
+  margin: 0 auto;
+}
+.byline {
+  color: var(--muted);
+}
+.prose table {
+  border-collapse: collapse;
+  width: 100%;
+}
+.prose th,
+.prose td {
+  border: 1px solid var(--border);
+  padding: 0.5rem;
+  text-align: left;
+}
+.prose img {
+  border-radius: 0.5rem;
+}
+.author {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+  border-top: 1px solid var(--border);
+  margin-top: 2rem;
+  padding-top: 1rem;
+}
+.avatar {
+  width: 4rem;
+  height: 4rem;
+  border-radius: 50%;
+  object-fit: cover;
+}
+.author-name {
+  font-weight: 700;
+  margin: 0;
+}
+.preview-banner {
+  background: #fef3c7;
+  color: #78350f;
+  padding: 0.5rem 1rem;
+  text-align: center;
+  font-weight: 600;
+}

package/templates/next/src/components/ArticleCard/index.tsx

@@ -0,0 +1,19 @@
+import { shapioAttr } from '@shapio/visual';
+import Link from 'next/link';
+import { articlePath, type Strings } from '../../lib/site';
+import type { Article } from '../../lib/types';
+import { Byline } from '../Byline';
+import { ResponsiveImage } from '../ResponsiveImage';
+
+type ArticleCardProps = { article: Article; locale: string; strings: Strings };
+
+export const ArticleCard = ({ article, locale, strings }: ArticleCardProps) => (
+  <li className="card">
+    {article.cover ? <ResponsiveImage media={article.cover} sizes="(min-width: 48rem) 33vw, 100vw" /> : null}
+    <h2 {...shapioAttr(article, 'title')}>
+      <Link href={articlePath(locale, article.slug)}>{article.title}</Link>
+    </h2>
+    <Byline article={article} locale={locale} strings={strings} />
+    {article.excerpt ? <p>{article.excerpt}</p> : null}
+  </li>
+);

package/templates/next/src/components/ArticleView/index.tsx

@@ -0,0 +1,40 @@
+import { shapioAttr } from '@shapio/visual';
+import { authorOf } from '../../lib/articles';
+import type { Strings } from '../../lib/site';
+import type { Article } from '../../lib/types';
+import { Byline } from '../Byline';
+import { ResponsiveImage } from '../ResponsiveImage';
+import { RichText } from '../RichText';
+
+type ArticleViewProps = { article: Article; locale: string; strings: Strings };
+
+export const ArticleView = ({ article, locale, strings }: ArticleViewProps) => {
+  const author = authorOf(article);
+  return (
+    <article className="article" lang={article.locale}>
+      <header>
+        <h1 {...shapioAttr(article, 'title')}>{article.title}</h1>
+        <Byline article={article} locale={locale} strings={strings} />
+      </header>
+      {article.cover ? (
+        <ResponsiveImage
+          media={article.cover}
+          sizes="(min-width: 48rem) 48rem, 100vw"
+          eager
+          className="cover"
+          visual={shapioAttr(article, 'cover')}
+        />
+      ) : null}
+      <RichText value={article.body} visual={shapioAttr(article, 'body')} />
+      {author ? (
+        <aside className="author">
+          {author.avatar ? <ResponsiveImage media={author.avatar} sizes="4rem" className="avatar" /> : null}
+          <div>
+            <p className="author-name">{author.name}</p>
+            {author.bio ? <p>{author.bio}</p> : null}
+          </div>
+        </aside>
+      ) : null}
+    </article>
+  );
+};

package/templates/next/src/components/Byline/index.tsx

@@ -0,0 +1,15 @@
+import { authorOf } from '../../lib/articles';
+import { formatDate, type Strings } from '../../lib/site';
+import type { Article } from '../../lib/types';
+
+type BylineProps = { article: Article; locale: string; strings: Strings };
+
+export const Byline = ({ article, locale, strings }: BylineProps) => {
+  const author = authorOf(article);
+  return (
+    <p className="byline">
+      {author ? `${strings.by} ${author.name} · ` : null}
+      <time dateTime={article.publishedOn}>{formatDate(article.publishedOn, locale)}</time>
+    </p>
+  );
+};

package/templates/next/src/components/LocaleSwitch/index.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import { switchLocale, type Locale } from '../../lib/site';
+
+type LocaleSwitchProps = { to: Locale; label: string };
+
+/** The current page in the other locale (slugs are shared across locales). */
+export const LocaleSwitch = ({ to, label }: LocaleSwitchProps) => {
+  const pathname = usePathname();
+  return (
+    <a href={switchLocale(pathname, to)} hrefLang={to} lang={to}>
+      {label}
+    </a>
+  );
+};

package/templates/next/src/components/Preview/hooks/usePreviewDraft.ts

@@ -0,0 +1,53 @@
+import { initVisualEditing } from '@shapio/visual';
+import { useEffect, useState } from 'react';
+import { publicShapioUrl } from '../../../lib/config';
+import { loadDraft, parsePreviewUrl, type PreviewDraft } from '../../../lib/preview';
+import { DEFAULT_LOCALE, type Locale } from '../../../lib/site';
+
+export type PreviewState =
+  | { status: 'loading'; locale: Locale }
+  | { status: 'incomplete'; locale: Locale }
+  | { status: 'failed'; locale: Locale; message: string }
+  | { status: 'ready'; locale: Locale; draft: PreviewDraft };
+
+/**
+ * Reads the preview request from the URL once, drops the token from the address bar, and loads the draft.
+ * Inside Shapio's preview pane, @shapio/visual turns on visual editing and re-loads the draft after each save
+ * (the token stays in memory: the address bar no longer has it).
+ */
+export const usePreviewDraft = (): PreviewState => {
+  const [state, setState] = useState<PreviewState>({ status: 'loading', locale: DEFAULT_LOCALE });
+  useEffect(() => {
+    const request = parsePreviewUrl(new URL(window.location.href));
+    // The token must not linger in the address bar, history or a shared screenshot.
+    window.history.replaceState(null, '', `${window.location.pathname}${window.location.search}`);
+    if (!request) {
+      setState({ status: 'incomplete', locale: DEFAULT_LOCALE });
+      return undefined;
+    }
+    let active = true;
+    const load = async () => {
+      try {
+        const draft = await loadDraft(publicShapioUrl(), request);
+        if (active) {
+          setState({ status: 'ready', locale: request.locale, draft });
+        }
+      } catch (error) {
+        if (active) {
+          setState({
+            status: 'failed',
+            locale: request.locale,
+            message: error instanceof Error ? error.message : String(error),
+          });
+        }
+      }
+    };
+    void load();
+    const stop = initVisualEditing({ origin: publicShapioUrl(), onRefresh: load });
+    return () => {
+      active = false;
+      stop();
+    };
+  }, []);
+  return state;
+};

package/templates/next/src/components/Preview/index.tsx

@@ -0,0 +1,33 @@
+'use client';
+import { stringsFor } from '../../lib/site';
+import { ArticleView } from '../ArticleView';
+import { Sections } from '../Sections';
+import { usePreviewDraft } from './hooks/usePreviewDraft';
+
+/** A draft page or article, rendered in the browser with the published pages' components. */
+export const Preview = () => {
+  const state = usePreviewDraft();
+  const strings = stringsFor(state.locale);
+  return (
+    <>
+      <div className="preview-banner" role="status">
+        {strings.previewBanner}
+      </div>
+      <main id="content" lang={state.locale}>
+        {state.status === 'loading' ? <p>{strings.previewLoading}</p> : null}
+        {state.status === 'incomplete' ? <p>{strings.previewIncomplete}</p> : null}
+        {state.status === 'failed' ? (
+          <p>
+            {strings.previewFailed}: {state.message}
+          </p>
+        ) : null}
+        {state.status === 'ready' && state.draft.modelKey === 'pages' ? (
+          <Sections page={state.draft.entry} />
+        ) : null}
+        {state.status === 'ready' && state.draft.modelKey === 'articles' ? (
+          <ArticleView article={state.draft.entry} locale={state.locale} strings={strings} />
+        ) : null}
+      </main>
+    </>
+  );
+};

package/templates/next/src/components/ResponsiveImage/index.tsx

@@ -0,0 +1,36 @@
+import type { ShapioAttributes } from '@shapio/visual';
+import type { Media } from '../../lib/types';
+
+type ResponsiveImageProps = {
+  media: Media;
+  sizes: string;
+  eager?: boolean;
+  className?: string;
+  /** The field the image shows (`shapioAttr`), for visual editing. */
+  visual?: ShapioAttributes;
+};
+
+/** WebP variants in `srcSet`, intrinsic size set (no layout shift), lazy unless eager. */
+export const ResponsiveImage = ({ media, sizes, eager = false, className, visual }: ResponsiveImageProps) => {
+  const widths = media.variants
+    .filter((variant) => variant.name.startsWith('w') && variant.width !== null)
+    .sort((a, b) => (a.width ?? 0) - (b.width ?? 0));
+  const largest = widths.at(-1);
+  return (
+    <img
+      src={largest?.url ?? media.url}
+      srcSet={
+        widths.length > 0 ? widths.map((variant) => `${variant.url} ${variant.width}w`).join(', ') : undefined
+      }
+      sizes={widths.length > 0 ? sizes : undefined}
+      width={media.width ?? undefined}
+      height={media.height ?? undefined}
+      alt={media.alt}
+      loading={eager ? 'eager' : 'lazy'}
+      fetchPriority={eager ? 'high' : undefined}
+      decoding="async"
+      className={className}
+      {...visual}
+    />
+  );
+};

package/templates/next/src/components/RichText/index.tsx

@@ -0,0 +1,13 @@
+import type { ShapioAttributes } from '@shapio/visual';
+import type { RichText as RichTextValue } from '../../lib/types';
+
+type RichTextProps = {
+  value: RichTextValue | null;
+  className?: string;
+  /** The field it shows (`shapioAttr`), for visual editing. */
+  visual?: ShapioAttributes;
+};
+
+/** Shapio's rich text arrives with a sanitised `html` rendering next to the JSON document. */
+export const RichText = ({ value, className = 'prose', visual }: RichTextProps) =>
+  value ? <div className={className} {...visual} dangerouslySetInnerHTML={{ __html: value.html }} /> : null;

package/templates/next/src/components/Sections/CallToAction/index.tsx

@@ -0,0 +1,14 @@
+import { safeHref } from '../../../lib/site';
+import type { CallToActionSection } from '../../../lib/types';
+
+type CallToActionProps = { section: CallToActionSection };
+
+export const CallToAction = ({ section }: CallToActionProps) => (
+  <section className="cta">
+    <h2>{section.heading}</h2>
+    {section.text ? <p>{section.text}</p> : null}
+    <a className="button" href={safeHref(section.buttonUrl)}>
+      {section.buttonLabel}
+    </a>
+  </section>
+);

package/templates/next/src/components/Sections/FeatureGrid/index.tsx

@@ -0,0 +1,17 @@
+import type { FeatureGridSection } from '../../../lib/types';
+
+type FeatureGridProps = { section: FeatureGridSection };
+
+export const FeatureGrid = ({ section }: FeatureGridProps) => (
+  <section className="features">
+    {section.heading ? <h2>{section.heading}</h2> : null}
+    <ul className="feature-grid">
+      {section.features.map((feature) => (
+        <li key={feature.title}>
+          <h3>{feature.title}</h3>
+          {feature.description ? <p>{feature.description}</p> : null}
+        </li>
+      ))}
+    </ul>
+  </section>
+);

package/templates/next/src/components/Sections/Gallery/index.tsx

@@ -0,0 +1,20 @@
+import type { GallerySection } from '../../../lib/types';
+import { ResponsiveImage } from '../../ResponsiveImage';
+
+type GalleryProps = { section: GallerySection };
+
+export const Gallery = ({ section }: GalleryProps) => (
+  <section className="gallery">
+    {section.heading ? <h2>{section.heading}</h2> : null}
+    <ul className="gallery-grid">
+      {section.images.map((image) => (
+        <li key={image.id}>
+          <figure>
+            <ResponsiveImage media={image} sizes="(min-width: 48rem) 33vw, 100vw" />
+            {image.caption ? <figcaption>{image.caption}</figcaption> : null}
+          </figure>
+        </li>
+      ))}
+    </ul>
+  </section>
+);