@jant/core 0.3.20 → 0.3.22

package/src/index.ts

@@ -10,7 +10,7 @@ import { createApp as _createApp } from "./app.js";
 export { createApp } from "./app.js";
 export type { App, AppVariables } from "./app.js";
 
-// Types (excluding component props to avoid conflicts with theme exports)
+// Types
 export type {
   PostType,
   Visibility,
@@ -29,10 +29,31 @@ export type {
   JantConfig,
   JantTheme,
   ThemeComponents,
+  // View Model types (for theme authors)
+  PostView,
+  MediaView,
+  NavLinkView,
+  SearchResultView,
+  TimelineItemView,
+  ArchiveGroup,
+  // Timeline types
   TimelineCardProps,
   ThreadPreviewProps,
-  TimelineItemData,
   TimelineFeedProps,
+  // Site layout
+  SiteLayoutProps,
+  // Page-level props (for theme authors)
+  HomePageProps,
+  PostPageProps,
+  SinglePageProps,
+  ArchivePageProps,
+  SearchPageProps,
+  CollectionPageProps,
+  // Feed types (for theme authors)
+  FeedData,
+  SitemapData,
+  // Search
+  SearchResult,
 } from "./types.js";
 
 export {
@@ -48,5 +69,33 @@ export * as sqid from "./lib/sqid.js";
 export * as url from "./lib/url.js";
 export * as markdown from "./lib/markdown.js";
 
+// View Model conversion utilities (for advanced theme use)
+export {
+  createMediaContext,
+  toPostView,
+  toPostViews,
+  toMediaView,
+  toNavLinkView,
+  toNavLinkViews,
+  toSearchResultView,
+  toArchiveGroups,
+} from "./lib/view.js";
+export type { MediaContext } from "./lib/view.js";
+
+// Render helper (for theme authors adding custom routes)
+export { renderPublicPage } from "./lib/render.js";
+export type { RenderPublicPageOptions } from "./lib/render.js";
+
+// Navigation helper (for theme authors)
+export { getNavigationData } from "./lib/navigation.js";
+export type { NavigationData } from "./lib/navigation.js";
+
+// Default feed renderers (for theme authors to extend)
+export {
+  defaultRssRenderer,
+  defaultAtomRenderer,
+  defaultSitemapRenderer,
+} from "./lib/feed.js";
+
 // Default export for running core directly (e.g., for development)
 export default _createApp();

package/src/lib/__tests__/theme-components.test.ts

@@ -1,15 +1,12 @@
 import { describe, it, expect } from "vitest";
-import {
-  resolveCardComponent,
-  resolveThreadPreview,
-  resolveTimelineFeed,
-} from "../theme-components.js";
+import { resolveCardComponent, resolveComponent } from "../theme-components.js";
 import type {
   ThemeComponents,
   TimelineCardProps,
   ThreadPreviewProps,
   TimelineFeedProps,
   PostType,
+  HomePageProps,
 } from "../../types.js";
 import type { FC } from "hono/jsx";
 
@@ -21,6 +18,7 @@ const MockQuoteCard: FC<TimelineCardProps> = () => null;
 const MockImageCard: FC<TimelineCardProps> = () => null;
 const MockThreadPreview: FC<ThreadPreviewProps> = () => null;
 const MockTimelineFeed: FC<TimelineFeedProps> = () => null;
+const MockHomePage: FC<HomePageProps> = () => null;
 
 const DEFAULT_CARD_MAP: Record<PostType, FC<TimelineCardProps>> = {
   note: MockNoteCard,
@@ -79,29 +77,50 @@ describe("theme-components", () => {
     });
   });
 
-  describe("resolveThreadPreview", () => {
+  describe("resolveComponent", () => {
     it("returns default ThreadPreview when no override", () => {
-      expect(resolveThreadPreview(MockThreadPreview)).toBe(MockThreadPreview);
+      expect(resolveComponent("ThreadPreview", MockThreadPreview)).toBe(
+        MockThreadPreview,
+      );
     });
 
-    it("returns theme override when provided", () => {
+    it("returns theme override for ThreadPreview when provided", () => {
       const Custom: FC<ThreadPreviewProps> = () => null;
       expect(
-        resolveThreadPreview(MockThreadPreview, { ThreadPreview: Custom }),
+        resolveComponent("ThreadPreview", MockThreadPreview, {
+          ThreadPreview: Custom,
+        }),
       ).toBe(Custom);
     });
-  });
 
-  describe("resolveTimelineFeed", () => {
     it("returns default TimelineFeed when no override", () => {
-      expect(resolveTimelineFeed(MockTimelineFeed)).toBe(MockTimelineFeed);
+      expect(resolveComponent("TimelineFeed", MockTimelineFeed)).toBe(
+        MockTimelineFeed,
+      );
     });
 
-    it("returns theme override when provided", () => {
+    it("returns theme override for TimelineFeed when provided", () => {
       const Custom: FC<TimelineFeedProps> = () => null;
       expect(
-        resolveTimelineFeed(MockTimelineFeed, { TimelineFeed: Custom }),
+        resolveComponent("TimelineFeed", MockTimelineFeed, {
+          TimelineFeed: Custom,
+        }),
       ).toBe(Custom);
     });
+
+    it("returns default HomePage when no override", () => {
+      expect(resolveComponent("HomePage", MockHomePage)).toBe(MockHomePage);
+    });
+
+    it("returns theme override for HomePage when provided", () => {
+      const Custom: FC<HomePageProps> = () => null;
+      expect(
+        resolveComponent("HomePage", MockHomePage, { HomePage: Custom }),
+      ).toBe(Custom);
+    });
+
+    it("returns default when theme has empty overrides", () => {
+      expect(resolveComponent("HomePage", MockHomePage, {})).toBe(MockHomePage);
+    });
   });
 });

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>`;
+}