@jant/core 0.3.21 → 0.3.22

package/src/lib/__tests__/view.test.ts

@@ -0,0 +1,375 @@
+/**
+ * View Model Conversion Tests
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  toPostView,
+  toPostViews,
+  toMediaView,
+  toNavLinkView,
+  toNavLinkViews,
+  toSearchResultView,
+  toArchiveGroups,
+} from "../view.js";
+import type { MediaContext } from "../view.js";
+import type {
+  PostWithMedia,
+  Media,
+  NavigationLink,
+  SearchResult,
+  Post,
+} from "../../types.js";
+
+const EMPTY_CTX: MediaContext = {};
+const CTX_WITH_URLS: MediaContext = {
+  r2PublicUrl: "https://cdn.example.com",
+  imageTransformUrl: "https://example.com/cdn-cgi/image",
+};
+
+function makePost(overrides: Partial<Post> = {}): Post {
+  return {
+    id: 1,
+    type: "note",
+    visibility: "featured",
+    title: null,
+    path: null,
+    content: "Hello world",
+    contentHtml: "<p>Hello world</p>",
+    sourceUrl: null,
+    sourceName: null,
+    sourceDomain: null,
+    replyToId: null,
+    threadId: null,
+    deletedAt: null,
+    publishedAt: 1706745600, // 2024-02-01T00:00:00Z
+    createdAt: 1706745600,
+    updatedAt: 1706745600,
+    ...overrides,
+  };
+}
+
+function makePostWithMedia(
+  overrides: Partial<PostWithMedia> = {},
+): PostWithMedia {
+  return {
+    ...makePost(overrides),
+    mediaAttachments: overrides.mediaAttachments ?? [],
+  };
+}
+
+function makeMedia(overrides: Partial<Media> = {}): Media {
+  return {
+    id: "01902a9f-1a2b-7c3d",
+    postId: 1,
+    filename: "image.webp",
+    originalName: "photo.jpg",
+    mimeType: "image/webp",
+    size: 12345,
+    storageKey: "media/2025/01/01902a9f-1a2b-7c3d.webp",
+    provider: "r2",
+    width: 1920,
+    height: 1080,
+    alt: "A photo",
+    position: 0,
+    blurhash: null,
+    createdAt: 1706745600,
+    ...overrides,
+  };
+}
+
+function makeNavLink(overrides: Partial<NavigationLink> = {}): NavigationLink {
+  return {
+    id: 1,
+    label: "Home",
+    url: "/",
+    position: 0,
+    createdAt: 1706745600,
+    updatedAt: 1706745600,
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// toPostView
+// =============================================================================
+
+describe("toPostView", () => {
+  it("generates permalink from post id", () => {
+    const post = makePostWithMedia({ id: 123 });
+    const view = toPostView(post, EMPTY_CTX);
+    expect(view.permalink).toMatch(/^\/p\/.+$/);
+    expect(view.permalink.length).toBeGreaterThan(3);
+  });
+
+  it("formats dates correctly", () => {
+    const post = makePostWithMedia({ publishedAt: 1706745600 });
+    const view = toPostView(post, EMPTY_CTX);
+    expect(view.publishedAt).toBe("2024-02-01T00:00:00.000Z");
+    expect(view.publishedAtFormatted).toBe("Feb 1, 2024");
+  });
+
+  it("generates excerpt from content", () => {
+    const shortContent = "Short text";
+    const longContent = "A".repeat(200);
+
+    const shortView = toPostView(
+      makePostWithMedia({ content: shortContent }),
+      EMPTY_CTX,
+    );
+    expect(shortView.excerpt).toBe("Short text");
+
+    const longView = toPostView(
+      makePostWithMedia({ content: longContent }),
+      EMPTY_CTX,
+    );
+    expect(longView.excerpt).toBe("A".repeat(160) + "...");
+  });
+
+  it("handles null content gracefully", () => {
+    const view = toPostView(makePostWithMedia({ content: null }), EMPTY_CTX);
+    expect(view.excerpt).toBeUndefined();
+    expect(view.content).toBeUndefined();
+  });
+
+  it("converts null fields to undefined", () => {
+    const view = toPostView(makePostWithMedia(), EMPTY_CTX);
+    expect(view.title).toBeUndefined();
+    expect(view.path).toBeUndefined();
+    expect(view.sourceUrl).toBeUndefined();
+    expect(view.sourceName).toBeUndefined();
+    expect(view.sourceDomain).toBeUndefined();
+    expect(view.replyToId).toBeUndefined();
+    expect(view.threadRootId).toBeUndefined();
+  });
+
+  it("preserves non-null source fields", () => {
+    const view = toPostView(
+      makePostWithMedia({
+        sourceUrl: "https://example.com",
+        sourceName: "Example",
+        sourceDomain: "example.com",
+      }),
+      EMPTY_CTX,
+    );
+    expect(view.sourceUrl).toBe("https://example.com");
+    expect(view.sourceName).toBe("Example");
+    expect(view.sourceDomain).toBe("example.com");
+  });
+
+  it("converts media attachments to MediaView", () => {
+    const view = toPostView(
+      makePostWithMedia({
+        mediaAttachments: [
+          {
+            id: "abc",
+            url: "/media/abc.webp",
+            previewUrl: "/media/abc-thumb.webp",
+            alt: "Photo",
+            blurhash: null,
+            width: 800,
+            height: 600,
+            position: 0,
+            mimeType: "image/webp",
+          },
+        ],
+      }),
+      EMPTY_CTX,
+    );
+    expect(view.media).toHaveLength(1);
+    expect(view.media[0]).toEqual({
+      id: "abc",
+      url: "/media/abc.webp",
+      thumbnailUrl: "/media/abc-thumb.webp",
+      mimeType: "image/webp",
+      altText: "Photo",
+      width: 800,
+      height: 600,
+    });
+  });
+});
+
+describe("toPostViews", () => {
+  it("converts multiple posts", () => {
+    const posts = [makePostWithMedia({ id: 1 }), makePostWithMedia({ id: 2 })];
+    const views = toPostViews(posts, EMPTY_CTX);
+    expect(views).toHaveLength(2);
+    expect(views[0]!.id).toBe(1);
+    expect(views[1]!.id).toBe(2);
+  });
+});
+
+// =============================================================================
+// toMediaView
+// =============================================================================
+
+describe("toMediaView", () => {
+  it("generates local proxy URL without public URL", () => {
+    const media = makeMedia();
+    const view = toMediaView(media, EMPTY_CTX);
+    expect(view.url).toBe("/media/01902a9f-1a2b-7c3d.webp");
+    expect(view.thumbnailUrl).toBe("/media/01902a9f-1a2b-7c3d.webp");
+  });
+
+  it("generates CDN URL with public URL", () => {
+    const media = makeMedia();
+    const view = toMediaView(media, CTX_WITH_URLS);
+    expect(view.url).toBe(
+      "https://cdn.example.com/media/2025/01/01902a9f-1a2b-7c3d.webp",
+    );
+    expect(view.thumbnailUrl).toContain("cdn-cgi/image");
+  });
+
+  it("uses S3 URL for s3 provider", () => {
+    const media = makeMedia({ provider: "s3" });
+    const ctx: MediaContext = {
+      r2PublicUrl: "https://r2.example.com",
+      s3PublicUrl: "https://s3.example.com",
+    };
+    const view = toMediaView(media, ctx);
+    expect(view.url).toContain("s3.example.com");
+  });
+
+  it("maps alt text and dimensions", () => {
+    const view = toMediaView(makeMedia(), EMPTY_CTX);
+    expect(view.altText).toBe("A photo");
+    expect(view.width).toBe(1920);
+    expect(view.height).toBe(1080);
+    expect(view.mimeType).toBe("image/webp");
+    expect(view.size).toBe(12345);
+  });
+
+  it("handles null alt and dimensions", () => {
+    const media = makeMedia({ alt: null, width: null, height: null });
+    const view = toMediaView(media, EMPTY_CTX);
+    expect(view.altText).toBeUndefined();
+    expect(view.width).toBeUndefined();
+    expect(view.height).toBeUndefined();
+  });
+});
+
+// =============================================================================
+// toNavLinkView
+// =============================================================================
+
+describe("toNavLinkView", () => {
+  it("marks home link active on exact / match", () => {
+    const view = toNavLinkView(makeNavLink({ url: "/" }), "/");
+    expect(view.isActive).toBe(true);
+    expect(view.isExternal).toBe(false);
+  });
+
+  it("marks home link inactive on other paths", () => {
+    const view = toNavLinkView(makeNavLink({ url: "/" }), "/archive");
+    expect(view.isActive).toBe(false);
+  });
+
+  it("matches prefix for non-root links", () => {
+    const view = toNavLinkView(makeNavLink({ url: "/archive" }), "/archive");
+    expect(view.isActive).toBe(true);
+
+    const viewSub = toNavLinkView(
+      makeNavLink({ url: "/archive" }),
+      "/archive/2024",
+    );
+    expect(viewSub.isActive).toBe(true);
+  });
+
+  it("does not false-match similar prefixes", () => {
+    const view = toNavLinkView(makeNavLink({ url: "/arch" }), "/archive");
+    expect(view.isActive).toBe(false);
+  });
+
+  it("marks external links as external and never active", () => {
+    const view = toNavLinkView(
+      makeNavLink({ url: "https://example.com" }),
+      "/",
+    );
+    expect(view.isExternal).toBe(true);
+    expect(view.isActive).toBe(false);
+  });
+
+  it("handles http:// links", () => {
+    const view = toNavLinkView(makeNavLink({ url: "http://example.com" }), "/");
+    expect(view.isExternal).toBe(true);
+    expect(view.isActive).toBe(false);
+  });
+});
+
+describe("toNavLinkViews", () => {
+  it("converts multiple links", () => {
+    const links = [
+      makeNavLink({ id: 1, url: "/" }),
+      makeNavLink({ id: 2, url: "/archive" }),
+      makeNavLink({ id: 3, url: "https://github.com" }),
+    ];
+    const views = toNavLinkViews(links, "/archive");
+    expect(views).toHaveLength(3);
+    expect(views[0]!.isActive).toBe(false);
+    expect(views[1]!.isActive).toBe(true);
+    expect(views[2]!.isExternal).toBe(true);
+  });
+});
+
+// =============================================================================
+// toSearchResultView
+// =============================================================================
+
+describe("toSearchResultView", () => {
+  it("wraps post in PostView", () => {
+    const result: SearchResult = {
+      post: makePost({ id: 42, title: "Test" }),
+      rank: 1.5,
+      snippet: "...matching <b>text</b>...",
+    };
+    const view = toSearchResultView(result, EMPTY_CTX);
+    expect(view.post.id).toBe(42);
+    expect(view.post.title).toBe("Test");
+    expect(view.post.permalink).toBeDefined();
+    expect(view.rank).toBe(1.5);
+    expect(view.snippet).toBe("...matching <b>text</b>...");
+  });
+});
+
+// =============================================================================
+// toArchiveGroups
+// =============================================================================
+
+describe("toArchiveGroups", () => {
+  it("converts grouped map to ArchiveGroup array", () => {
+    const grouped = new Map<string, Post[]>();
+    grouped.set("2024-02", [
+      makePost({ id: 1, publishedAt: 1706745600 }),
+      makePost({ id: 2, publishedAt: 1706832000 }),
+    ]);
+    grouped.set("2024-01", [makePost({ id: 3, publishedAt: 1704067200 })]);
+
+    const groups = toArchiveGroups(grouped, EMPTY_CTX);
+    expect(groups).toHaveLength(2);
+
+    expect(groups[0]!.year).toBe("2024");
+    expect(groups[0]!.month).toBe("02");
+    expect(groups[0]!.label).toBe("February 2024");
+    expect(groups[0]!.posts).toHaveLength(2);
+
+    expect(groups[1]!.year).toBe("2024");
+    expect(groups[1]!.month).toBe("01");
+    expect(groups[1]!.label).toBe("January 2024");
+    expect(groups[1]!.posts).toHaveLength(1);
+  });
+
+  it("converts posts to PostView within groups", () => {
+    const grouped = new Map<string, Post[]>();
+    grouped.set("2024-02", [makePost({ id: 1 })]);
+
+    const groups = toArchiveGroups(grouped, EMPTY_CTX);
+    const post = groups[0]!.posts[0]!;
+    expect(post.permalink).toBeDefined();
+    expect(post.publishedAtFormatted).toBeDefined();
+  });
+
+  it("handles empty map", () => {
+    const groups = toArchiveGroups(new Map(), EMPTY_CTX);
+    expect(groups).toHaveLength(0);
+  });
+});

package/src/lib/feed.ts

@@ -0,0 +1,148 @@
+/**
+ * Default Feed Renderers
+ *
+ * RSS 2.0, Atom, and Sitemap XML generators.
+ * Theme authors can import these to extend/wrap the defaults:
+ *
+ * @example
+ * ```typescript
+ * import { defaultRssRenderer } from "@jant/core/lib/feed";
+ * ```
+ */
+
+import type { FeedData, SitemapData } from "../types.js";
+
+/**
+ * Escape special XML characters.
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Default RSS 2.0 renderer.
+ *
+ * @param data - Feed data with PostView[] (pre-computed URLs)
+ * @returns RSS 2.0 XML string
+ */
+export function defaultRssRenderer(data: FeedData): string {
+  const { siteName, siteDescription, siteUrl, siteLanguage, posts } = data;
+
+  const items = posts
+    .map((post) => {
+      const link = `${siteUrl}${post.permalink}`;
+      const title = post.title || `Post #${post.id}`;
+      const pubDate = new Date(post.publishedAt).toUTCString();
+
+      // Add enclosure for first media attachment
+      const firstMedia = post.media[0];
+      const enclosure = firstMedia
+        ? `\n      <enclosure url="${firstMedia.url}" type="${firstMedia.mimeType}"${firstMedia.size ? ` length="${firstMedia.size}"` : ""}/>`
+        : "";
+
+      return `
+    <item>
+      <title><![CDATA[${escapeXml(title)}]]></title>
+      <link>${link}</link>
+      <guid isPermaLink="true">${link}</guid>
+      <pubDate>${pubDate}</pubDate>
+      <description><![CDATA[${post.contentHtml || ""}]]></description>${enclosure}
+    </item>`;
+    })
+    .join("");
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml(siteName)}</title>
+    <link>${siteUrl}</link>
+    <description>${escapeXml(siteDescription)}</description>
+    <language>${siteLanguage}</language>
+    <atom:link href="${siteUrl}/feed" rel="self" type="application/rss+xml"/>
+    ${items}
+  </channel>
+</rss>`;
+}
+
+/**
+ * Default Atom renderer.
+ *
+ * @param data - Feed data with PostView[] (pre-computed URLs)
+ * @returns Atom XML string
+ */
+export function defaultAtomRenderer(data: FeedData): string {
+  const { siteName, siteDescription, siteUrl, posts } = data;
+
+  const entries = posts
+    .map((post) => {
+      const link = `${siteUrl}${post.permalink}`;
+      const title = post.title || `Post #${post.id}`;
+
+      return `
+  <entry>
+    <title>${escapeXml(title)}</title>
+    <link href="${link}" rel="alternate"/>
+    <id>${link}</id>
+    <published>${post.publishedAt}</published>
+    <updated>${post.updatedAt}</updated>
+    <content type="html"><![CDATA[${post.contentHtml || ""}]]></content>
+  </entry>`;
+    })
+    .join("");
+
+  const now = new Date().toISOString();
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns="http://www.w3.org/2005/Atom">
+  <title>${escapeXml(siteName)}</title>
+  <subtitle>${escapeXml(siteDescription)}</subtitle>
+  <link href="${siteUrl}" rel="alternate"/>
+  <link href="${siteUrl}/feed/atom.xml" rel="self"/>
+  <id>${siteUrl}/</id>
+  <updated>${now}</updated>
+  ${entries}
+</feed>`;
+}
+
+/**
+ * Default Sitemap renderer.
+ *
+ * @param data - Sitemap data with PostView[] (pre-computed URLs)
+ * @returns Sitemap XML string
+ */
+export function defaultSitemapRenderer(data: SitemapData): string {
+  const { siteUrl, posts } = data;
+
+  const urls = posts
+    .map((post) => {
+      const loc = `${siteUrl}${post.permalink}`;
+      const lastmod = post.updatedAt.split("T")[0];
+      const priority = post.visibility === "featured" ? "0.8" : "0.6";
+
+      return `
+  <url>
+    <loc>${loc}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <priority>${priority}</priority>
+  </url>`;
+    })
+    .join("");
+
+  const homepageUrl = `
+  <url>
+    <loc>${siteUrl}/</loc>
+    <priority>1.0</priority>
+    <changefreq>daily</changefreq>
+  </url>`;
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+  ${homepageUrl}
+  ${urls}
+</urlset>`;
+}

package/src/lib/navigation.ts

@@ -6,13 +6,14 @@
 
 import type { Context } from "hono";
 import { getSiteName } from "./config.js";
-import type { NavigationLink } from "../types.js";
+import type { NavLinkView } from "../types.js";
+import { toNavLinkViews } from "./view.js";
 
 /**
  * Navigation data needed by SiteLayout
  */
 export interface NavigationData {
-  navigationLinks: NavigationLink[];
+  links: NavLinkView[];
   currentPath: string;
   siteName: string;
 }
@@ -21,7 +22,7 @@ export interface NavigationData {
  * Fetch navigation data for public pages.
  *
  * Ensures default links exist (Home, Archive, RSS) and returns
- * the current path and site name alongside the links.
+ * NavLinkView[] with pre-computed isActive/isExternal state.
  *
  * @param c - Hono context
  * @returns Navigation data for SiteLayout
@@ -29,18 +30,17 @@ export interface NavigationData {
  * @example
  * ```typescript
  * const navData = await getNavigationData(c);
- * return c.html(
- *   <BaseLayout c={c}>
- *     <SiteLayout {...navData}>
- *       <MyContent />
- *     </SiteLayout>
- *   </BaseLayout>
- * );
+ * return renderPublicPage(c, {
+ *   title: "My Page",
+ *   navData,
+ *   content: <MyContent />,
+ * });
  * ```
  */
 export async function getNavigationData(c: Context): Promise<NavigationData> {
   const navigationLinks = await c.var.services.navigationLinks.ensureDefaults();
   const currentPath = new URL(c.req.url).pathname;
   const siteName = await getSiteName(c);
-  return { navigationLinks, currentPath, siteName };
+  const links = toNavLinkViews(navigationLinks, currentPath);
+  return { links, currentPath, siteName };
 }

package/src/lib/render.tsx

@@ -0,0 +1,67 @@
+/**
+ * Public Page Rendering Helper
+ *
+ * Provides a single entry point for rendering public pages with the
+ * correct layout stack: BaseLayout > SiteLayout > content.
+ *
+ * BaseLayout is always the built-in implementation (handles Vite assets,
+ * I18nProvider, toast). SiteLayout is resolved from theme components.
+ */
+
+import type { Context } from "hono";
+import type { Child } from "hono/jsx";
+import type { ThemeComponents, SiteLayoutProps } from "../types.js";
+import { BaseLayout } from "../theme/layouts/BaseLayout.js";
+import { SiteLayout as DefaultSiteLayout } from "../theme/layouts/SiteLayout.js";
+import type { NavigationData } from "./navigation.js";
+
+export interface RenderPublicPageOptions {
+  /** Page title for <title> tag */
+  title: string;
+  /** Page description for meta tag */
+  description?: string;
+  /** Navigation data (from getNavigationData) */
+  navData: NavigationData;
+  /** Page content JSX to render inside SiteLayout */
+  content: Child;
+}
+
+/**
+ * Render a public page with the standard layout stack.
+ *
+ * Always uses the built-in BaseLayout, resolves SiteLayout from theme config.
+ *
+ * @param c - Hono context
+ * @param options - Page rendering options
+ * @returns Hono HTML response
+ *
+ * @example
+ * ```typescript
+ * const navData = await getNavigationData(c);
+ * return renderPublicPage(c, {
+ *   title: "My Page",
+ *   navData,
+ *   content: <MyPageComponent />,
+ * });
+ * ```
+ */
+export function renderPublicPage(c: Context, options: RenderPublicPageOptions) {
+  const { title, description, navData, content } = options;
+
+  const components = c.var.config?.theme?.components as
+    | ThemeComponents
+    | undefined;
+  const Layout = components?.SiteLayout ?? DefaultSiteLayout;
+
+  const layoutProps: SiteLayoutProps = {
+    siteName: navData.siteName,
+    links: navData.links,
+    currentPath: navData.currentPath,
+  };
+
+  return c.html(
+    <BaseLayout title={title} description={description} c={c}>
+      <Layout {...layoutProps}>{content}</Layout>
+    </BaseLayout>,
+  );
+}