@jant/core 0.3.21 → 0.3.22

package/dist/app.js

@@ -56,7 +56,7 @@ import { createStorageDriver } from "./lib/storage.js";
  * import { createApp } from "@jant/core";
  *
  * export default createApp({
- *   theme: { components: { PostCard: MyPostCard } },
+ *   theme: { components: { PostPage: MyPostPage } },
  * });
  * ```
  */ export function createApp(config = {}) {

package/dist/index.js

@@ -11,5 +11,13 @@ export * as time from "./lib/time.js";
 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";
+// Render helper (for theme authors adding custom routes)
+export { renderPublicPage } from "./lib/render.js";
+// Navigation helper (for theme authors)
+export { getNavigationData } 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/dist/lib/feed.js

@@ -0,0 +1,112 @@
+/**
+ * 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";
+ * ```
+ */ /**
+ * Escape special XML characters.
+ */ function escapeXml(str) {
+    return str.replace(/&/g, "&amp;").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) {
+    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) {
+    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) {
+    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/dist/lib/navigation.js

@@ -3,11 +3,12 @@
  *
  * Provides shared data fetching for public page navigation.
  */ import { getSiteName } from "./config.js";
+import { toNavLinkViews } from "./view.js";
 /**
  * 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
@@ -15,20 +16,19 @@
  * @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) {
     const navigationLinks = await c.var.services.navigationLinks.ensureDefaults();
     const currentPath = new URL(c.req.url).pathname;
     const siteName = await getSiteName(c);
+    const links = toNavLinkViews(navigationLinks, currentPath);
     return {
-        navigationLinks,
+        links,
         currentPath,
         siteName
     };

package/dist/lib/render.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { jsx as _jsx } from "hono/jsx/jsx-runtime";
+import { BaseLayout } from "../theme/layouts/BaseLayout.js";
+import { SiteLayout as DefaultSiteLayout } from "../theme/layouts/SiteLayout.js";
+/**
+ * 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, options) {
+    const { title, description, navData, content } = options;
+    const components = c.var.config?.theme?.components;
+    const Layout = components?.SiteLayout ?? DefaultSiteLayout;
+    const layoutProps = {
+        siteName: navData.siteName,
+        links: navData.links,
+        currentPath: navData.currentPath
+    };
+    return c.html(/*#__PURE__*/ _jsx(BaseLayout, {
+        title: title,
+        description: description,
+        c: c,
+        children: /*#__PURE__*/ _jsx(Layout, {
+            ...layoutProps,
+            children: content
+        })
+    }));
+}

package/dist/lib/theme-components.js

@@ -10,6 +10,24 @@
     image: "ImageCard",
     page: "NoteCard"
 };
+/**
+ * Generic component resolver.
+ *
+ * Looks up a component by key in `ThemeComponents` and falls back to the
+ * provided default component.
+ *
+ * @param key - ThemeComponents key to look up
+ * @param defaultComponent - Fallback component
+ * @param themeComponents - Optional theme component overrides
+ * @returns The resolved component
+ *
+ * @example
+ * ```ts
+ * const Gallery = resolveComponent("MediaGallery", DefaultMediaGallery, theme);
+ * ```
+ */ export function resolveComponent(key, defaultComponent, themeComponents) {
+    return themeComponents?.[key] ?? defaultComponent;
+}
 /**
  * Resolves the card component for a given post type.
  *
@@ -29,21 +47,3 @@
     const override = themeComponents?.[key];
     return override ?? defaults[type];
 }
-/**
- * Resolves the ThreadPreview component.
- *
- * @param defaultComponent - The default ThreadPreview component
- * @param themeComponents - Optional theme component overrides
- * @returns The resolved ThreadPreview component
- */ export function resolveThreadPreview(defaultComponent, themeComponents) {
-    return themeComponents?.ThreadPreview ?? defaultComponent;
-}
-/**
- * Resolves the TimelineFeed component.
- *
- * @param defaultComponent - The default TimelineFeed component
- * @param themeComponents - Optional theme component overrides
- * @returns The resolved TimelineFeed component
- */ export function resolveTimelineFeed(defaultComponent, themeComponents) {
-    return themeComponents?.TimelineFeed ?? defaultComponent;
-}

package/dist/lib/view.js

@@ -0,0 +1,228 @@
+/**
+ * View Model Conversions
+ *
+ * Transforms raw database models into render-ready View types.
+ * Theme components receive only View types — no lib/ imports needed.
+ */ import { encode } from "./sqid.js";
+import { toISOString, formatDate } from "./time.js";
+import { getMediaUrl, getImageUrl, getPublicUrlForProvider } from "./image.js";
+/**
+ * Creates a MediaContext from Hono context environment variables.
+ *
+ * @param c - Hono context
+ * @returns MediaContext with env values
+ *
+ * @example
+ * ```ts
+ * const mediaCtx = createMediaContext(c);
+ * const postView = toPostView(post, mediaCtx);
+ * ```
+ */ export function createMediaContext(c) {
+    return {
+        r2PublicUrl: c.env.R2_PUBLIC_URL,
+        imageTransformUrl: c.env.IMAGE_TRANSFORM_URL,
+        s3PublicUrl: c.env.S3_PUBLIC_URL
+    };
+}
+// =============================================================================
+// Media Conversions
+// =============================================================================
+/**
+ * Converts a raw Media record to a render-ready MediaView.
+ *
+ * @param media - Raw media record from database
+ * @param ctx - Media context with URL configuration
+ * @returns Render-ready MediaView with pre-computed URLs
+ */ export function toMediaView(media, ctx) {
+    const publicUrl = getPublicUrlForProvider(media.provider, ctx.r2PublicUrl, ctx.s3PublicUrl);
+    const url = getMediaUrl(media.id, media.storageKey, publicUrl);
+    const thumbnailUrl = getImageUrl(url, ctx.imageTransformUrl, {
+        width: 400,
+        quality: 80,
+        format: "auto",
+        fit: "cover"
+    });
+    return {
+        id: media.id,
+        url,
+        thumbnailUrl,
+        mimeType: media.mimeType,
+        altText: media.alt ?? undefined,
+        width: media.width ?? undefined,
+        height: media.height ?? undefined,
+        size: media.size
+    };
+}
+// =============================================================================
+// Post Conversions
+// =============================================================================
+/**
+ * Converts a PostWithMedia to a render-ready PostView.
+ *
+ * @param post - Post with media attachments from database
+ * @param ctx - Media context with URL configuration
+ * @returns Render-ready PostView with pre-computed fields
+ *
+ * @example
+ * ```ts
+ * const mediaCtx = createMediaContext(c);
+ * const postView = toPostView({ ...post, mediaAttachments: [...] }, mediaCtx);
+ * ```
+ */ export function toPostView(post, ctx) {
+    const permalink = `/p/${encode(post.id)}`;
+    // Pre-compute excerpt from raw content
+    let excerpt;
+    if (post.content) {
+        excerpt = post.content.length > 160 ? post.content.slice(0, 160) + "..." : post.content;
+    }
+    // Convert media attachments
+    const media = post.mediaAttachments.map((m)=>({
+            id: m.id,
+            url: m.url,
+            thumbnailUrl: m.previewUrl,
+            mimeType: m.mimeType,
+            altText: m.alt ?? undefined,
+            width: m.width ?? undefined,
+            height: m.height ?? undefined
+        }));
+    return {
+        id: post.id,
+        permalink,
+        title: post.title ?? undefined,
+        contentHtml: post.contentHtml ?? undefined,
+        excerpt,
+        type: post.type,
+        visibility: post.visibility,
+        path: post.path ?? undefined,
+        publishedAt: toISOString(post.publishedAt),
+        publishedAtFormatted: formatDate(post.publishedAt),
+        updatedAt: toISOString(post.updatedAt),
+        sourceUrl: post.sourceUrl ?? undefined,
+        sourceName: post.sourceName ?? undefined,
+        sourceDomain: post.sourceDomain ?? undefined,
+        media,
+        replyToId: post.replyToId ?? undefined,
+        threadRootId: post.threadId ?? undefined,
+        content: post.content ?? undefined
+    };
+}
+/**
+ * Batch converts PostWithMedia[] to PostView[].
+ *
+ * @param posts - Array of posts with media
+ * @param ctx - Media context
+ * @returns Array of PostView
+ */ export function toPostViews(posts, ctx) {
+    return posts.map((p)=>toPostView(p, ctx));
+}
+/**
+ * Converts a bare Post (no media) to a PostView with empty media array.
+ *
+ * @param post - Post without media
+ * @param ctx - Media context (unused but kept for consistency)
+ * @returns PostView with empty media
+ */ export function toPostViewFromPost(post, ctx) {
+    return toPostView({
+        ...post,
+        mediaAttachments: []
+    }, ctx);
+}
+/**
+ * Batch converts Post[] (no media) to PostView[].
+ *
+ * @param posts - Array of posts without media
+ * @param ctx - Media context
+ * @returns Array of PostView
+ */ export function toPostViewsFromPosts(posts, ctx) {
+    return posts.map((p)=>toPostViewFromPost(p, ctx));
+}
+// =============================================================================
+// Navigation Conversions
+// =============================================================================
+/**
+ * Converts a NavigationLink to a NavLinkView with pre-computed state.
+ *
+ * @param link - Raw navigation link from database
+ * @param currentPath - Current page path for active state computation
+ * @returns NavLinkView with isActive and isExternal pre-computed
+ */ export function toNavLinkView(link, currentPath) {
+    const isExternal = link.url.startsWith("http://") || link.url.startsWith("https://");
+    let isActive = false;
+    if (!isExternal) {
+        if (link.url === "/") {
+            isActive = currentPath === "/";
+        } else {
+            isActive = currentPath === link.url || currentPath.startsWith(link.url + "/");
+        }
+    }
+    return {
+        id: link.id,
+        label: link.label,
+        url: link.url,
+        isActive,
+        isExternal
+    };
+}
+/**
+ * Batch converts NavigationLink[] to NavLinkView[].
+ *
+ * @param links - Raw navigation links
+ * @param currentPath - Current page path
+ * @returns Array of NavLinkView
+ */ export function toNavLinkViews(links, currentPath) {
+    return links.map((l)=>toNavLinkView(l, currentPath));
+}
+// =============================================================================
+// Search Result Conversions
+// =============================================================================
+/**
+ * Converts a SearchResult to a SearchResultView with PostView.
+ *
+ * @param result - Raw search result
+ * @param ctx - Media context
+ * @returns SearchResultView with PostView
+ */ export function toSearchResultView(result, ctx) {
+    return {
+        post: toPostViewFromPost(result.post, ctx),
+        rank: result.rank,
+        snippet: result.snippet
+    };
+}
+/**
+ * Batch converts SearchResult[] to SearchResultView[].
+ *
+ * @param results - Raw search results
+ * @param ctx - Media context
+ * @returns Array of SearchResultView
+ */ export function toSearchResultViews(results, ctx) {
+    return results.map((r)=>toSearchResultView(r, ctx));
+}
+// =============================================================================
+// Archive Group Conversions
+// =============================================================================
+/**
+ * Converts a grouped post map to typed ArchiveGroup[].
+ *
+ * @param grouped - Map of "YYYY-MM" keys to Post arrays
+ * @param ctx - Media context
+ * @returns Array of ArchiveGroup with pre-formatted labels
+ */ export function toArchiveGroups(grouped, ctx) {
+    const groups = [];
+    for (const [yearMonth, posts] of grouped){
+        const [year, month] = yearMonth.split("-");
+        if (!year || !month) continue;
+        // Format label like "February 2024"
+        const date = new Date(parseInt(year, 10), parseInt(month, 10) - 1);
+        const label = date.toLocaleDateString("en-US", {
+            year: "numeric",
+            month: "long"
+        });
+        groups.push({
+            year,
+            month,
+            label,
+            posts: toPostViewsFromPosts(posts, ctx)
+        });
+    }
+    return groups;
+}

package/dist/routes/api/timeline.js

@@ -7,7 +7,8 @@ import { jsx as _jsx } from "hono/jsx/jsx-runtime";
 import { sse } from "../../lib/sse.js";
 import { buildMediaMap } from "../../lib/media-helpers.js";
 import { TimelineItem } from "../../theme/components/timeline/TimelineItem.js";
-import { ThreadPreview } from "../../theme/components/timeline/ThreadPreview.js";
+import { ThreadPreview as DefaultThreadPreview } from "../../theme/components/timeline/ThreadPreview.js";
+import { createMediaContext, toPostView, toPostViews } from "../../lib/view.js";
 const PAGE_SIZE = 20;
 export const timelineApiRoutes = new Hono();
 timelineApiRoutes.get("/", async (c)=>{
@@ -41,10 +42,8 @@ timelineApiRoutes.get("/", async (c)=>{
     // Build media map
     const postIds = displayPosts.map((p)=>p.id);
     const rawMediaMap = await c.var.services.media.getByPostIds(postIds);
-    const r2PublicUrl = c.env.R2_PUBLIC_URL;
-    const imageTransformUrl = c.env.IMAGE_TRANSFORM_URL;
-    const s3PublicUrl = c.env.S3_PUBLIC_URL;
-    const mediaMap = buildMediaMap(rawMediaMap, r2PublicUrl, imageTransformUrl, s3PublicUrl);
+    const mediaCtx = createMediaContext(c);
+    const mediaMap = buildMediaMap(rawMediaMap, mediaCtx.r2PublicUrl, mediaCtx.imageTransformUrl, mediaCtx.s3PublicUrl);
     // Get reply counts to identify thread roots
     const replyCounts = await c.var.services.posts.getReplyCounts(postIds);
     const threadRootIds = postIds.filter((id)=>(replyCounts.get(id) ?? 0) > 0);
@@ -57,42 +56,47 @@ timelineApiRoutes.get("/", async (c)=>{
             previewReplyIds.push(reply.id);
         }
     }
-    const previewMediaMap = previewReplyIds.length > 0 ? buildMediaMap(await c.var.services.media.getByPostIds(previewReplyIds), r2PublicUrl, imageTransformUrl, s3PublicUrl) : new Map();
-    // Assemble timeline items
+    const previewMediaMap = previewReplyIds.length > 0 ? buildMediaMap(await c.var.services.media.getByPostIds(previewReplyIds), mediaCtx.r2PublicUrl, mediaCtx.imageTransformUrl, mediaCtx.s3PublicUrl) : new Map();
+    // Assemble timeline items with View Models
     const items = displayPosts.map((post)=>{
-        const postWithMedia = {
+        const postView = toPostView({
             ...post,
             mediaAttachments: mediaMap.get(post.id) ?? []
-        };
+        }, mediaCtx);
         const replyCount = replyCounts.get(post.id) ?? 0;
         const previewReplies = threadPreviews.get(post.id);
         if (replyCount > 0 && previewReplies) {
             return {
-                post: postWithMedia,
+                post: postView,
                 threadPreview: {
-                    replies: previewReplies.map((r)=>({
+                    replies: toPostViews(previewReplies.map((r)=>({
                             ...r,
                             mediaAttachments: previewMediaMap.get(r.id) ?? []
-                        })),
+                        })), mediaCtx),
                     totalReplyCount: replyCount
                 }
             };
         }
         return {
-            post: postWithMedia
+            post: postView
         };
     });
+    // Resolve theme components for card rendering
+    const theme = c.var.config.theme?.components;
+    const ResolvedThreadPreview = theme?.ThreadPreview ?? DefaultThreadPreview;
     // Render items to HTML
     const itemsHtml = items.map((item)=>{
         if (item.threadPreview) {
-            return /*#__PURE__*/ _jsx(ThreadPreview, {
+            return /*#__PURE__*/ _jsx(ResolvedThreadPreview, {
                 rootPost: item.post,
                 previewReplies: item.threadPreview.replies,
-                totalReplyCount: item.threadPreview.totalReplyCount
+                totalReplyCount: item.threadPreview.totalReplyCount,
+                theme: theme
             });
         }
         return /*#__PURE__*/ _jsx(TimelineItem, {
-            item: item
+            item: item,
+            theme: theme
         });
     }).map((jsx)=>jsx.toString()).join("");
     // Determine next cursor