@django-stack/cli 0.3.0 → 0.5.0

package/templates/frontend-sveltekit/src/lib/headless.ts

@@ -0,0 +1,344 @@
+// Generated by django-headless from the OpenAPI schema of the API. Do not edit this file:
+// run `headless generate` again when the exposed models change.
+
+export interface ContentAuthor {
+  id: number;
+  name: string;
+  slug: string;
+  bio: string;
+  avatar: string | null;
+}
+
+export interface ContentCategory {
+  id: number;
+  name: string;
+  slug: string;
+  description: string;
+}
+
+export interface ContentFormSubmission {
+  id: number;
+  name: string;
+  /** Format: email. */
+  email: string;
+  message: string;
+  /** Format: date-time. */
+  created_at: string;
+}
+
+export interface ContentFormSubmissionInput {
+  name: string;
+  /** Format: email. */
+  email: string;
+  message: string;
+}
+
+export interface ContentMenu {
+  id: number;
+  name: string;
+  /** The frontend asks for a menu by this name, such as main. */
+  slug: string;
+  items: { [key: string]: unknown };
+}
+
+export interface ContentPage {
+  id: number;
+  status: "draft" | "published";
+  /** Leave empty to publish right away. A future date schedules the publication. Format: date-time. */
+  published_at: string | null;
+  seo_title: string;
+  seo_description: string;
+  title: string;
+  slug: string;
+  path: string;
+  body: { [key: string]: unknown };
+  order: number;
+  /** Shown when the page is shared; 1200 × 630 works best. */
+  share_image: string | null;
+  parent: number | null;
+  is_published: boolean;
+}
+
+export interface ContentPost {
+  id: number;
+  status: "draft" | "published";
+  /** Leave empty to publish right away. A future date schedules the publication. Format: date-time. */
+  published_at: string | null;
+  seo_title: string;
+  seo_description: string;
+  title: string;
+  slug: string;
+  /** A short summary for lists and search results. */
+  excerpt: string;
+  body: { [key: string]: unknown };
+  /** Shown when the page is shared; 1200 × 630 works best. */
+  share_image: string | null;
+  cover: string | null;
+  author: number | null;
+  categories: number[];
+  tags: number[];
+  is_published: boolean;
+}
+
+export interface ContentRedirect {
+  id: number;
+  /** Such as /old-page, without the domain. */
+  old_path: string;
+  /** A path on the site or a full URL. */
+  new_path: string;
+  /** 301 when on, 302 when off. */
+  permanent: boolean;
+}
+
+export interface ContentSiteSettings {
+  id: number;
+  site_name: string;
+  tagline: string;
+  seo_description: string;
+  /** Such as {"Mastodon": "https://..."}. */
+  social_links: { [key: string]: unknown };
+  footer_text: string;
+  logo: string | null;
+  /** The page shown at /. Without one, the home page lists the latest posts. */
+  home_page: number | null;
+  /** The default image for social sharing. */
+  share_image: string | null;
+}
+
+export interface ContentStudioMediaLibraryMedia {
+  /** Format: uuid. */
+  id: string;
+  name: string;
+  /** Describes a picture for screen readers */
+  alt_text: string;
+  type: "image" | "video" | "audio" | "file";
+  /** Format: binary. */
+  file: string;
+  /** Read from the file, such as an image's width and height. */
+  metadata: { [key: string]: unknown };
+  /** Set by editors for some types of media, such as a focal point. */
+  properties: { [key: string]: unknown };
+}
+
+export interface ContentTag {
+  id: number;
+  name: string;
+  slug: string;
+}
+
+export type Models = {
+  "content.author": {
+    item: ContentAuthor;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+      bio: string;
+      avatar: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+      avatar: { model: "content_studio_media_library.media"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.category": {
+    item: ContentCategory;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+      description: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.formsubmission": {
+    item: ContentFormSubmission;
+    input: ContentFormSubmissionInput;
+    id: number;
+    filters: {
+      id: number;
+      name: string;
+      email: string;
+      message: string;
+      created_at: string | Date;
+    };
+    lookups: {};
+    expandable: {};
+    readOnly: false;
+    singleton: false;
+    paginated: true;
+  };
+  "content.menu": {
+    item: ContentMenu;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      name: string;
+      slug: string;
+      items: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.page": {
+    item: ContentPage;
+    input: never;
+    id: number;
+    filters: {
+      children: number;
+      id: number;
+      status: "draft" | "published";
+      published_at: string | Date;
+      seo_title: string;
+      seo_description: string;
+      share_image: string;
+      title: string;
+      slug: string;
+      parent: number;
+      path: string;
+      body: string;
+      order: number;
+    };
+    lookups: {};
+    expandable: {
+      children: { model: "content.page"; many: true; nullable: false };
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      parent: { model: "content.page"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.post": {
+    item: ContentPost;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      status: "draft" | "published";
+      published_at: string | Date;
+      seo_title: string;
+      seo_description: string;
+      share_image: string;
+      title: string;
+      slug: string;
+      excerpt: string;
+      cover: string;
+      body: string;
+      author: number;
+      categories: number;
+      tags: number;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      cover: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      author: { model: "content.author"; many: false; nullable: true };
+      categories: { model: "content.category"; many: true; nullable: false };
+      tags: { model: "content.tag"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.redirect": {
+    item: ContentRedirect;
+    input: never;
+    id: number;
+    filters: {
+      id: number;
+      old_path: string;
+      new_path: string;
+      permanent: boolean;
+    };
+    lookups: {
+      old_path: string;
+    };
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content.sitesettings": {
+    item: ContentSiteSettings;
+    input: never;
+    id: string | number;
+    filters: {};
+    lookups: {};
+    expandable: {
+      logo: { model: "content_studio_media_library.media"; many: false; nullable: true };
+      home_page: { model: "content.page"; many: false; nullable: true };
+      share_image: { model: "content_studio_media_library.media"; many: false; nullable: true };
+    };
+    readOnly: true;
+    singleton: true;
+    paginated: true;
+  };
+  "content.tag": {
+    item: ContentTag;
+    input: never;
+    id: number;
+    filters: {
+      posts: number;
+      id: number;
+      name: string;
+      slug: string;
+    };
+    lookups: {
+      slug: string;
+    };
+    expandable: {
+      posts: { model: "content.post"; many: true; nullable: false };
+    };
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+  "content_studio_media_library.media": {
+    item: ContentStudioMediaLibraryMedia;
+    input: never;
+    id: string;
+    filters: {
+      id: string;
+      file: string;
+      name: string;
+      alt_text: string;
+      metadata: string;
+      properties: string;
+      type: "image" | "video" | "audio" | "file";
+    };
+    lookups: {};
+    expandable: {};
+    readOnly: true;
+    singleton: false;
+    paginated: true;
+  };
+};

package/templates/frontend-sveltekit/src/lib/server/api.ts

@@ -0,0 +1,28 @@
+/**
+ * Content access for load functions and endpoints. Server-side only: the API
+ * key is read from API_READ_KEY, and SvelteKit never sends modules in
+ * src/lib/server to the browser.
+ */
+
+import { createClient, createContent } from "@django-stack/utils";
+import type { Cookies } from "@sveltejs/kit";
+import type { Models } from "../headless";
+
+export const PREVIEW_COOKIE = "stack_preview";
+
+/** The content helpers, with drafts when the request carries a preview cookie. */
+export function getContent(cookies: Cookies) {
+  return createContent(getClient(cookies));
+}
+
+/** The typed Django Headless client, for queries the content helpers do not cover. */
+export function getClient(cookies?: Cookies) {
+  return createClient<Models>({ previewToken: cookies?.get(PREVIEW_COOKIE) ?? null });
+}
+
+export const SITE_URL = (process.env.SITE_URL ?? "http://localhost:3000").replace(/\/$/, "");
+
+/** The page number of a list, from ?page=. */
+export function pageNumber(url: URL): number {
+  return Math.max(1, Number(url.searchParams.get("page")) || 1);
+}

package/templates/frontend-sveltekit/src/lib/server/cache.ts

@@ -0,0 +1,58 @@
+/**
+ * A small in-memory cache of rendered pages. Django calls /revalidate after
+ * editors change content, which empties it; entries also expire after
+ * CACHE_TTL seconds (default 300). One frontend process, one cache: with
+ * several replicas, put a shared cache or CDN in front instead.
+ */
+
+interface Entry {
+  body: string;
+  status: number;
+  headers: [string, string][];
+  expires: number;
+}
+
+const MAX_ENTRIES = Number(process.env.CACHE_MAX_ENTRIES ?? 500);
+const TTL = Number(process.env.CACHE_TTL ?? 300) * 1000;
+const entries = new Map<string, Entry>();
+
+export function getCached(key: string): Response | null {
+  const entry = entries.get(key);
+  if (!entry) return null;
+  if (entry.expires < Date.now()) {
+    entries.delete(key);
+    return null;
+  }
+  // Move to the end: the oldest entries are evicted first.
+  entries.delete(key);
+  entries.set(key, entry);
+  const headers = new Headers(entry.headers);
+  headers.set("X-Cache", "HIT");
+  return new Response(entry.body, { status: entry.status, headers });
+}
+
+export async function store(key: string, response: Response): Promise<Response> {
+  if (TTL <= 0) return response;
+  const body = await response.text();
+  entries.set(key, {
+    body,
+    status: response.status,
+    headers: [...response.headers.entries()].filter(([name]) => name.toLowerCase() !== "set-cookie"),
+    expires: Date.now() + TTL,
+  });
+  while (entries.size > MAX_ENTRIES) {
+    const oldest = entries.keys().next().value;
+    if (oldest === undefined) break;
+    entries.delete(oldest);
+  }
+  const headers = new Headers(response.headers);
+  headers.set("X-Cache", "MISS");
+  return new Response(body, { status: response.status, headers });
+}
+
+/** Empties the cache; returns the number of entries removed. */
+export function purgeAll(): number {
+  const size = entries.size;
+  entries.clear();
+  return size;
+}

package/templates/frontend-sveltekit/src/lib/server/rss.ts

@@ -0,0 +1,44 @@
+/** An RSS 2.0 feed. */
+
+export interface FeedItem {
+  title: string;
+  /** A path on the site, such as /blog/hello-world. */
+  link: string;
+  description?: string | null;
+  pubDate?: Date | null;
+}
+
+const escapeXml = (text: string) =>
+  text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+export function rssFeed(feed: {
+  title: string;
+  description: string;
+  site: string;
+  items: FeedItem[];
+}): string {
+  const items = feed.items.map((item) => {
+    const url = escapeXml(new URL(item.link, `${feed.site}/`).href);
+    return [
+      "    <item>",
+      `      <title>${escapeXml(item.title)}</title>`,
+      `      <link>${url}</link>`,
+      `      <guid isPermaLink="true">${url}</guid>`,
+      item.description ? `      <description>${escapeXml(item.description)}</description>` : "",
+      item.pubDate ? `      <pubDate>${item.pubDate.toUTCString()}</pubDate>` : "",
+      "    </item>",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  });
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0">
+  <channel>
+    <title>${escapeXml(feed.title)}</title>
+    <description>${escapeXml(feed.description)}</description>
+    <link>${escapeXml(`${feed.site}/`)}</link>
+${items.join("\n")}
+  </channel>
+</rss>
+`;
+}

package/templates/frontend-sveltekit/src/routes/+error.svelte

@@ -0,0 +1,14 @@
+<script lang="ts">
+  import { page } from "$app/state";
+</script>
+
+<section class="narrow">
+  {#if page.status === 404}
+    <h1>Page not found</h1>
+    <p>The page you are looking for does not exist or has moved.</p>
+  {:else}
+    <h1>Something went wrong</h1>
+    <p>The page could not be shown. Try again in a moment.</p>
+  {/if}
+  <p><a href="/">Go to the home page</a></p>
+</section>

package/templates/frontend-sveltekit/src/routes/+layout.server.ts

@@ -0,0 +1,18 @@
+import { getContent, PREVIEW_COOKIE, SITE_URL } from "#lib/server/api.ts";
+import type { LayoutServerLoad } from "./$types";
+
+export const load: LayoutServerLoad = async ({ cookies }) => {
+  const content = getContent(cookies);
+  const [settings, mainMenu, footerMenu] = await Promise.all([
+    content.getSiteSettings(),
+    content.getMenu("main"),
+    content.getMenu("footer"),
+  ]);
+  return {
+    settings,
+    mainMenu,
+    footerMenu,
+    preview: cookies.get(PREVIEW_COOKIE) !== undefined,
+    siteUrl: SITE_URL,
+  };
+};

package/templates/frontend-sveltekit/src/routes/+layout.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+  import "../app.css";
+  import { page } from "$app/state";
+  import { Image, RichText, Seo } from "@django-stack/svelte";
+  import { linkHref } from "@django-stack/utils";
+
+  let { data, children } = $props();
+  const path = $derived(page.url.pathname);
+  const seo = $derived(
+    page.error ? { title: page.status === 404 ? "Page not found" : "Something went wrong" } : page.data.seo,
+  );
+</script>
+
+<svelte:head>
+  <link rel="alternate" type="application/rss+xml" title={data.settings?.site_name ?? "RSS"} href="/rss.xml" />
+</svelte:head>
+
+<Seo
+  page={seo ?? null}
+  type={page.data.seoType}
+  settings={data.settings}
+  siteUrl={data.siteUrl}
+  path={path}
+/>
+
+{#if data.preview}
+  <div class="preview-banner">
+    Preview: drafts are shown. <a href="/preview/exit" data-sveltekit-reload>Leave preview</a>
+  </div>
+{/if}
+<header class="site-header">
+  <div class="container bar">
+    <a class="brand" href="/">
+      {#if data.settings?.logo}
+        <Image media={data.settings.logo} size="thumbnail" alt={data.settings.site_name} eager />
+      {:else}
+        {data.settings?.site_name}
+      {/if}
+    </a>
+    <nav aria-label="Main">
+      {#each data.mainMenu?.items ?? [] as item (item.id)}
+        {@const href = linkHref(item)}
+        <a {href} aria-current={href === path || (href !== "/" && path.startsWith(`${href}/`)) ? "page" : undefined}>
+          {item.value.label}
+        </a>
+      {/each}
+    </nav>
+  </div>
+</header>
+<main>
+  {@render children()}
+</main>
+<footer class="site-footer">
+  <div class="container bar muted">
+    <RichText html={data.settings?.footer_text} class="footer-text" />
+    <nav aria-label="Footer">
+      {#each data.footerMenu?.items ?? [] as item (item.id)}
+        <a href={linkHref(item)}>{item.value.label}</a>
+      {/each}
+      {#each Object.entries(data.settings?.social_links ?? {}) as [name, url] (name)}
+        <a href={url} rel="me">{name}</a>
+      {/each}
+    </nav>
+  </div>
+</footer>
+
+<style>
+  .site-header {
+    border-bottom: 1px solid var(--color-line);
+  }
+  .bar {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1rem;
+    align-items: center;
+    justify-content: space-between;
+    padding-block: 1rem;
+  }
+  .brand {
+    font-weight: 700;
+    font-size: 1.2rem;
+    color: inherit;
+    text-decoration: none;
+  }
+  .brand :global(img) {
+    height: 2.5rem;
+    width: auto;
+  }
+  nav {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 1.25rem;
+  }
+  nav a {
+    text-decoration: none;
+  }
+  nav a[aria-current="page"] {
+    font-weight: 600;
+    text-decoration: underline;
+  }
+  main {
+    min-height: 70vh;
+    padding-block: 2rem 4rem;
+  }
+  .site-footer {
+    border-top: 1px solid var(--color-line);
+    font-size: 0.9rem;
+  }
+  .site-footer :global(.footer-text p) {
+    margin: 0;
+  }
+</style>

package/templates/frontend-sveltekit/src/routes/+page.server.ts

@@ -0,0 +1,10 @@
+import { getContent } from "#lib/server/api.ts";
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = async ({ cookies }) => {
+  const content = getContent(cookies);
+  const settings = await content.getSiteSettings();
+  const home = await content.getHomePage(settings);
+  const posts = home ? null : await content.getPosts({ limit: 9 });
+  return { home, posts, seo: home };
+};

package/templates/frontend-sveltekit/src/routes/+page.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import PostList from "#lib/components/PostList.svelte";
+  import { Blocks } from "@django-stack/svelte";
+
+  let { data } = $props();
+</script>
+
+{#if data.home}
+  <article class="narrow">
+    <h1>{data.home.title}</h1>
+    <Blocks blocks={data.home.body} />
+  </article>
+{:else}
+  <section class="container">
+    <h1>{data.settings?.site_name ?? "Latest posts"}</h1>
+    {#if data.settings?.tagline}<p class="muted">{data.settings.tagline}</p>{/if}
+    {#if data.posts}<PostList result={data.posts} base="/" />{/if}
+  </section>
+{/if}

package/templates/frontend-sveltekit/src/routes/[...path]/+page.server.ts

@@ -0,0 +1,9 @@
+import { error } from "@sveltejs/kit";
+import { getContent } from "#lib/server/api.ts";
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = async ({ params, cookies }) => {
+  const page = await getContent(cookies).getPage(params.path);
+  if (!page) error(404, "Page not found");
+  return { page, seo: page };
+};

package/templates/frontend-sveltekit/src/routes/[...path]/+page.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+  import ContactForm from "#lib/components/ContactForm.svelte";
+  import { Blocks } from "@django-stack/svelte";
+
+  let { data } = $props();
+</script>
+
+<article class="narrow">
+  <h1>{data.page.title}</h1>
+  <Blocks blocks={data.page.body} />
+  {#if data.page.path === "contact"}<ContactForm />{/if}
+</article>

package/templates/frontend-sveltekit/src/routes/blog/+page.server.ts

@@ -0,0 +1,7 @@
+import { getContent, pageNumber } from "#lib/server/api.ts";
+import type { PageServerLoad } from "./$types";
+
+export const load: PageServerLoad = async ({ cookies, url }) => {
+  const result = await getContent(cookies).getPosts({ page: pageNumber(url), limit: 9 });
+  return { result, seo: { title: "Blog" } };
+};

package/templates/frontend-sveltekit/src/routes/blog/+page.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import PostList from "#lib/components/PostList.svelte";
+
+  let { data } = $props();
+</script>
+
+<section class="container">
+  <h1>Blog</h1>
+  <PostList result={data.result} base="/blog" />
+</section>