create-shapio 0.2.0

package/templates/sveltekit/src/lib/components/ArticleView.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  import { shapioAttr } from '@shapio/visual';
+  import { authorOf } from '../articles';
+  import type { Strings } from '../site';
+  import type { Article } from '../types';
+  import Byline from './Byline.svelte';
+  import ResponsiveImage from './ResponsiveImage.svelte';
+  import RichText from './RichText.svelte';
+
+  type Props = { article: Article; locale: string; strings: Strings };
+  let { article, locale, strings }: Props = $props();
+  const author = $derived(authorOf(article));
+</script>
+
+<article class="article" lang={article.locale}>
+  <header>
+    <h1 {...shapioAttr(article, 'title')}>{article.title}</h1>
+    <Byline {article} {locale} {strings} />
+  </header>
+  {#if article.cover}
+    <ResponsiveImage
+      media={article.cover}
+      sizes="(min-width: 48rem) 48rem, 100vw"
+      eager
+      class="cover"
+      visual={shapioAttr(article, 'cover')}
+    />
+  {/if}
+  <RichText value={article.body} visual={shapioAttr(article, 'body')} />
+  {#if author}
+    <aside class="author">
+      {#if author.avatar}
+        <ResponsiveImage media={author.avatar} sizes="4rem" class="avatar" />
+      {/if}
+      <div>
+        <p class="author-name">{author.name}</p>
+        {#if author.bio}
+          <p>{author.bio}</p>
+        {/if}
+      </div>
+    </aside>
+  {/if}
+</article>

package/templates/sveltekit/src/lib/components/Byline.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { authorOf } from '../articles';
+  import { formatDate, type Strings } from '../site';
+  import type { Article } from '../types';
+
+  type Props = { article: Article; locale: string; strings: Strings };
+  let { article, locale, strings }: Props = $props();
+  const author = $derived(authorOf(article));
+</script>
+
+<p class="byline">
+  {#if author}{strings.by} {author.name} ·
+  {/if}<time datetime={article.publishedOn}>{formatDate(article.publishedOn, locale)}</time>
+</p>

package/templates/sveltekit/src/lib/components/CallToAction.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import { safeHref } from '../site';
+  import type { CallToActionSection } from '../types';
+
+  type Props = { section: CallToActionSection };
+  let { section }: Props = $props();
+</script>
+
+<section class="cta">
+  <h2>{section.heading}</h2>
+  {#if section.text}
+    <p>{section.text}</p>
+  {/if}
+  <a class="button" href={safeHref(section.buttonUrl)}>{section.buttonLabel}</a>
+</section>

package/templates/sveltekit/src/lib/components/FeatureGrid.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+  import type { FeatureGridSection } from '../types';
+
+  type Props = { section: FeatureGridSection };
+  let { section }: Props = $props();
+</script>
+
+<section class="features">
+  {#if section.heading}
+    <h2>{section.heading}</h2>
+  {/if}
+  <ul class="feature-grid">
+    {#each section.features as feature (feature.title)}
+      <li>
+        <h3>{feature.title}</h3>
+        {#if feature.description}
+          <p>{feature.description}</p>
+        {/if}
+      </li>
+    {/each}
+  </ul>
+</section>

package/templates/sveltekit/src/lib/components/Gallery.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import type { GallerySection } from '../types';
+  import ResponsiveImage from './ResponsiveImage.svelte';
+
+  type Props = { section: GallerySection };
+  let { section }: Props = $props();
+</script>
+
+<section class="gallery">
+  {#if section.heading}
+    <h2>{section.heading}</h2>
+  {/if}
+  <ul class="gallery-grid">
+    {#each section.images as image (image.id)}
+      <li>
+        <figure>
+          <ResponsiveImage media={image} sizes="(min-width: 48rem) 33vw, 100vw" />
+          {#if image.caption}
+            <figcaption>{image.caption}</figcaption>
+          {/if}
+        </figure>
+      </li>
+    {/each}
+  </ul>
+</section>

package/templates/sveltekit/src/lib/components/Hero.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+  import type { ShapioAttributes } from '@shapio/visual';
+  import { safeHref } from '../site';
+  import type { HeroSection } from '../types';
+  import ResponsiveImage from './ResponsiveImage.svelte';
+
+  type Props = { section: HeroSection; isFirst: boolean; visual?: ShapioAttributes };
+  let { section, isFirst, visual }: Props = $props();
+</script>
+
+<section class="hero">
+  <div class="hero-text">
+    <svelte:element this={isFirst ? 'h1' : 'h2'} {...visual}>{section.heading}</svelte:element>
+    {#if section.subheading}
+      <p class="lead">{section.subheading}</p>
+    {/if}
+    {#if section.ctaLabel && section.ctaUrl}
+      <a class="button" href={safeHref(section.ctaUrl)}>{section.ctaLabel}</a>
+    {/if}
+  </div>
+  {#if section.image}
+    <ResponsiveImage media={section.image} sizes="(min-width: 64rem) 50vw, 100vw" eager={isFirst} class="hero-image" />
+  {/if}
+</section>

package/templates/sveltekit/src/lib/components/ResponsiveImage.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  import type { ShapioAttributes } from '@shapio/visual';
+  import type { Media } from '../types';
+
+  /** `visual`: the field the image shows (`shapioAttr`), for visual editing. */
+  type Props = { media: Media; sizes: string; eager?: boolean; class?: string; visual?: ShapioAttributes };
+  let { media, sizes, eager = false, class: className, visual }: Props = $props();
+
+  // WebP variants in srcset, intrinsic size set (no layout shift), lazy unless eager.
+  const widths = $derived(
+    media.variants
+      .filter((variant) => variant.name.startsWith('w') && variant.width !== null)
+      .sort((a, b) => (a.width ?? 0) - (b.width ?? 0)),
+  );
+  const srcset = $derived(widths.map((variant) => `${variant.url} ${variant.width}w`).join(', '));
+</script>
+
+<img
+  src={widths.at(-1)?.url ?? media.url}
+  srcset={srcset || undefined}
+  sizes={srcset ? sizes : undefined}
+  width={media.width ?? undefined}
+  height={media.height ?? undefined}
+  alt={media.alt}
+  loading={eager ? 'eager' : 'lazy'}
+  fetchpriority={eager ? 'high' : undefined}
+  decoding="async"
+  class={className}
+  {...visual}
+/>

package/templates/sveltekit/src/lib/components/RichText.svelte

@@ -0,0 +1,13 @@
+<script lang="ts">
+  import type { ShapioAttributes } from '@shapio/visual';
+  import type { RichText } from '../types';
+
+  /** `visual`: the field it shows (`shapioAttr`), for visual editing. */
+  type Props = { value: RichText | null; visual?: ShapioAttributes };
+  let { value, visual }: Props = $props();
+</script>
+
+<!-- Shapio's rich text arrives with a sanitised `html` rendering next to the JSON document. -->
+{#if value}
+  <div class="prose" {...visual}>{@html value.html}</div>
+{/if}

package/templates/sveltekit/src/lib/components/Sections.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  import { shapioAttr } from '@shapio/visual';
+  import type { Page } from '../types';
+  import CallToAction from './CallToAction.svelte';
+  import FeatureGrid from './FeatureGrid.svelte';
+  import Gallery from './Gallery.svelte';
+  import Hero from './Hero.svelte';
+
+  /** A page's dynamic zone. The page title is the heading when the page does not open with a hero. */
+  type Props = { page: Pick<Page, 'id' | 'title' | 'sections' | 'locale'> };
+  let { page }: Props = $props();
+</script>
+
+<div lang={page.locale}>
+  {#if page.sections[0]?.__component !== 'hero'}
+    <h1 class="page-title" {...shapioAttr(page, 'title')}>{page.title}</h1>
+  {/if}
+  {#each page.sections as section, index (`${section.__component}-${index}`)}
+    {#if section.__component === 'hero'}
+      <Hero {section} isFirst={index === 0} visual={shapioAttr(page, `sections/${index}/heading`)} />
+    {:else if section.__component === 'featureGrid'}
+      <FeatureGrid {section} />
+    {:else if section.__component === 'gallery'}
+      <Gallery {section} />
+    {:else if section.__component === 'callToAction'}
+      <CallToAction {section} />
+    {/if}
+    <!-- Any other section type (added in Shapio after the last deploy) is skipped. -->
+  {/each}
+</div>

package/templates/sveltekit/src/lib/preview.ts

@@ -0,0 +1,56 @@
+import { createClient } from '@shapio/client';
+import { DEFAULT_LOCALE, isLocale, type Locale } from './site';
+import type { Article, DeliveryItem, Page } from './types';
+
+/**
+ * Preview: Shapio opens `/preview/?model={modelKey}&id={entryId}&locale={locale}#token={token}` (the
+ * connection's preview URL template). `{modelKey}` is the model's route key (`pages`, `articles`). The token
+ * sits in the fragment, so it never reaches a server log or a Referer header; it is a scoped, expiring preview
+ * token, never an admin credential. The draft is read in the browser from `/api/preview/content/...` and
+ * rendered with the same components as the prerendered pages.
+ */
+export const PREVIEW_MODELS = ['pages', 'articles'] as const;
+
+export type PreviewRequest = {
+  token: string;
+  modelKey: (typeof PREVIEW_MODELS)[number];
+  entryId: string;
+  locale: Locale;
+};
+
+export type PreviewDraft =
+  | { modelKey: 'pages'; entry: Page; locale: Locale }
+  | { modelKey: 'articles'; entry: Article; locale: Locale };
+
+/** Reads the request from a preview URL; undefined when something is missing or unknown. */
+export const parsePreviewUrl = (url: URL): PreviewRequest | undefined => {
+  const fragment = new URLSearchParams(url.hash.slice(1));
+  const token = fragment.get('token') ?? url.searchParams.get('token');
+  const modelKey = url.searchParams.get('model');
+  const entryId = url.searchParams.get('id');
+  const locale = url.searchParams.get('locale') ?? DEFAULT_LOCALE;
+  if (!token || !entryId || !(PREVIEW_MODELS as readonly string[]).includes(modelKey ?? '')) {
+    return undefined;
+  }
+  return {
+    token,
+    modelKey: modelKey as PreviewRequest['modelKey'],
+    entryId,
+    locale: isLocale(locale) ? locale : DEFAULT_LOCALE,
+  };
+};
+
+/** Fetches the draft through the preview API. */
+export const loadDraft = async (shapioUrl: string, request: PreviewRequest): Promise<PreviewDraft> => {
+  const client = createClient({ baseUrl: shapioUrl, token: request.token });
+  const params = new URLSearchParams({
+    locale: request.locale,
+    ...(request.modelKey === 'articles' ? { populate: 'author' } : {}),
+  });
+  const { data } = await client.request<DeliveryItem<Page | Article>>(
+    `/api/preview/content/${encodeURIComponent(request.modelKey)}/${encodeURIComponent(request.entryId)}?${params.toString()}`,
+  );
+  return request.modelKey === 'pages'
+    ? { modelKey: 'pages', entry: data as Page, locale: request.locale }
+    : { modelKey: 'articles', entry: data as Article, locale: request.locale };
+};

package/templates/sveltekit/src/lib/server/config.ts

@@ -0,0 +1,46 @@
+import {
+  PUBLIC_SHAPIO_URL,
+  SHAPIO_DELIVERY_TOKEN,
+  SHAPIO_SITE,
+  SHAPIO_SNAPSHOT,
+  SHAPIO_URL,
+} from '$app/env/private';
+
+/**
+ * Build-time settings, from the environment (or `.env` in this folder, which `npm run seed` writes), declared
+ * in src/env.ts:
+ * - SHAPIO_URL: the Shapio origin (with BASE_PATH), e.g. https://cms.example.com.
+ * - SHAPIO_DELIVERY_TOKEN: a read-only delivery token (Settings → API tokens, delivery role).
+ * - SHAPIO_SNAPSHOT: optional; the publication snapshot to build. Without it the build pins the latest
+ *   snapshot when prerendering starts, so every page shows the same moment.
+ * - SHAPIO_SITE: optional; the site key on a multi-site Shapio (default: the token's site, else the primary).
+ * - PUBLIC_SHAPIO_URL: the Shapio URL the browser calls for previews (defaults to SHAPIO_URL).
+ */
+export const shapioUrl = () => SHAPIO_URL ?? 'http://localhost:4300';
+
+/** Handed to the preview page at build time: the URL its browser code reads drafts from. */
+export const publicShapioUrl = () => PUBLIC_SHAPIO_URL ?? shapioUrl();
+
+export const deliveryToken = () => {
+  const token = SHAPIO_DELIVERY_TOKEN;
+  if (!token) {
+    throw new Error(
+      'Set SHAPIO_DELIVERY_TOKEN (a Shapio delivery token) to build the site; `npm run seed` writes one to .env',
+    );
+  }
+  return token;
+};
+
+export const siteKey = () => SHAPIO_SITE;
+
+export const configuredSnapshot = (): number | undefined => {
+  const value = SHAPIO_SNAPSHOT;
+  if (value === undefined) {
+    return undefined;
+  }
+  const snapshot = Number(value);
+  if (!Number.isInteger(snapshot) || snapshot < 0) {
+    throw new Error(`SHAPIO_SNAPSHOT must be a publication snapshot number, got "${value}"`);
+  }
+  return snapshot;
+};

package/templates/sveltekit/src/lib/server/shapio.ts

@@ -0,0 +1,93 @@
+import { createClient, ShapioApiError, type DeliveryListQuery } from '@shapio/client';
+import type { Locale } from '../site';
+import type { Article, Page, SiteSettings } from '../types';
+import { configuredSnapshot, deliveryToken, shapioUrl, siteKey } from './config';
+
+/**
+ * The site's read side: Shapio's delivery API through `@shapio/client`, pinned to one publication snapshot
+ * for the whole build. The snapshot is read once, when prerendering starts (or taken from SHAPIO_SNAPSHOT),
+ * and sent with every request, so a publish during the build never yields a site that mixes old and new.
+ */
+const PAGE_SIZE = 100;
+
+/** Delivery addresses a collection by its plural API ID, a singleton by its API ID. */
+const PAGES = 'pages';
+const ARTICLES = 'articles';
+const SITE_SETTINGS = 'siteSettings';
+
+/** The fields each read renders (`fields=`): smaller responses, and accurate field usage in Shapio. */
+const PAGE_FIELDS = ['title', 'slug', 'description', 'sections'];
+const ARTICLE_FIELDS = ['title', 'slug', 'excerpt', 'body', 'cover', 'author', 'publishedOn'];
+const SITE_SETTINGS_FIELDS = ['siteName', 'tagline', 'footer', 'colophon'];
+
+const createShapio = () => createClient({ baseUrl: shapioUrl(), token: deliveryToken(), site: siteKey() });
+
+let client: ReturnType<typeof createShapio> | undefined;
+const shapio = () => (client ??= createShapio());
+
+let pinned: Promise<number> | undefined;
+
+/** The snapshot every request of this build reads. */
+const snapshot = (): Promise<number> =>
+  (pinned ??= (async () => configuredSnapshot() ?? (await shapio().snapshots.current()).snapshot)());
+
+/** Each collection is read once per locale, however many pages render from it. */
+const memo = new Map<string, Promise<unknown>>();
+const once = <T>(key: string, read: () => Promise<T>): Promise<T> => {
+  let value = memo.get(key) as Promise<T> | undefined;
+  if (!value) {
+    value = read();
+    memo.set(key, value);
+  }
+  return value;
+};
+
+/** Every published entry of a collection in one locale, page by page, at the pinned snapshot. */
+const listAll = async <T>(routeKey: string, query: DeliveryListQuery): Promise<T[]> => {
+  const entries: T[] = [];
+  for (let page = 1; ; page += 1) {
+    const result = await shapio().delivery.list<T>(routeKey, {
+      ...query,
+      snapshot: await snapshot(),
+      page,
+      pageSize: PAGE_SIZE,
+    });
+    entries.push(...result.data);
+    if (page >= result.meta.pagination.pageCount) {
+      return entries;
+    }
+  }
+};
+
+export const listPages = (locale: Locale) =>
+  once(`pages:${locale}`, () => listAll<Page>(PAGES, { locale, fields: PAGE_FIELDS }));
+
+export const listArticles = (locale: Locale) =>
+  once(`articles:${locale}`, () =>
+    listAll<Article>(ARTICLES, {
+      locale,
+      fields: ARTICLE_FIELDS,
+      populate: ['author'],
+      sort: [{ field: 'publishedOn', direction: 'desc' }],
+    }),
+  );
+
+/** The siteSettings singleton in one locale; null until it is published. */
+export const getSiteSettings = (locale: Locale): Promise<SiteSettings | null> =>
+  once(`settings:${locale}`, () => readSiteSettings(locale));
+
+const readSiteSettings = async (locale: Locale): Promise<SiteSettings | null> => {
+  try {
+    const { data } = await shapio().delivery.singleton<SiteSettings>(SITE_SETTINGS, {
+      locale,
+      snapshot: await snapshot(),
+      fields: SITE_SETTINGS_FIELDS,
+    });
+    return data;
+  } catch (error) {
+    if (error instanceof ShapioApiError && error.status === 404) {
+      return null;
+    }
+    throw error;
+  }
+};

package/templates/sveltekit/src/lib/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/sveltekit/src/lib/site.ts

@@ -0,0 +1,66 @@
+/** The site's locales (they must exist in Shapio: the seed creates `fr`; `en` is Shapio's default). */
+export const LOCALES = ['en', 'fr'] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = 'en';
+
+/** The page whose slug is `home` is each locale's front page. */
+export const HOME_SLUG = 'home';
+
+export const isLocale = (value: string): value is Locale => (LOCALES as readonly string[]).includes(value);
+
+/** Reads a route's `[locale]` segment; the layout only generates known locales (dynamicParams = false). */
+export const toLocale = (value: string): Locale => (isLocale(value) ? value : DEFAULT_LOCALE);
+
+const STRINGS = {
+  en: {
+    siteName: 'Northwind Studio',
+    articles: 'Journal',
+    colophon: 'Colophon',
+    by: 'By',
+    switchTo: 'Français',
+    skipToContent: 'Skip to content',
+    footer: 'Built with Shapio',
+    previewBanner: 'Preview: this is a draft, not the published page.',
+    previewLoading: 'Loading the draft…',
+    previewFailed: 'The preview could not be loaded',
+    previewIncomplete: 'This preview link is incomplete.',
+  },
+  fr: {
+    siteName: 'Studio Northwind',
+    articles: 'Journal',
+    colophon: 'Colophon',
+    by: 'Par',
+    switchTo: 'English',
+    skipToContent: 'Aller au contenu',
+    footer: 'Construit avec Shapio',
+    previewBanner: 'Aperçu : ceci est un brouillon, pas la page publiée.',
+    previewLoading: 'Chargement du brouillon…',
+    previewFailed: "L'aperçu n'a pas pu être chargé",
+    previewIncomplete: "Ce lien d'aperçu est incomplet.",
+  },
+} as const satisfies Record<Locale, Record<string, string>>;
+
+export type Strings = (typeof STRINGS)[Locale];
+
+export const stringsFor = (locale: Locale): Strings => STRINGS[locale];
+
+export const otherLocale = (locale: Locale): Locale => (locale === 'en' ? 'fr' : 'en');
+
+export const formatDate = (iso: string, locale: string) =>
+  new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(new Date(iso));
+
+export const pagePath = (locale: string, slug: string) =>
+  slug === HOME_SLUG ? `/${locale}/` : `/${locale}/${slug}/`;
+export const articlesPath = (locale: string) => `/${locale}/articles/`;
+export const articlePath = (locale: string, slug: string) => `/${locale}/articles/${slug}/`;
+export const colophonPath = (locale: string) => `/${locale}/colophon/`;
+
+/** The same path in another locale (slugs are shared across locales in this starter's models). */
+export const switchLocale = (pathname: string, locale: Locale) =>
+  pathname.replace(/^\/(en|fr)(?=\/|$)/, `/${locale}`);
+
+/** Links from content: web, mail, phone and site-relative only (a `javascript:` URL becomes `#`). */
+export const safeHref = (value: string | null | undefined): string => {
+  const href = (value ?? '').trim();
+  return /^(https?:\/\/|mailto:|tel:|\/(?!\/)|#)/i.test(href) ? href : '#';
+};