@jant/core 0.3.20 → 0.3.22

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>,
+  );
+}

package/src/lib/theme-components.ts

@@ -5,13 +5,7 @@
  */
 
 import type { FC } from "hono/jsx";
-import type {
-  PostType,
-  ThemeComponents,
-  TimelineCardProps,
-  ThreadPreviewProps,
-  TimelineFeedProps,
-} from "../types.js";
+import type { PostType, ThemeComponents, TimelineCardProps } from "../types.js";
 
 const THEME_KEY_MAP: Record<PostType, keyof ThemeComponents> = {
   note: "NoteCard",
@@ -22,6 +16,32 @@ const THEME_KEY_MAP: Record<PostType, keyof ThemeComponents> = {
   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<K extends keyof ThemeComponents>(
+  key: K,
+  defaultComponent: NonNullable<ThemeComponents[K]>,
+  themeComponents?: ThemeComponents,
+): NonNullable<ThemeComponents[K]> {
+  return (themeComponents?.[key] ?? defaultComponent) as NonNullable<
+    ThemeComponents[K]
+  >;
+}
+
 /**
  * Resolves the card component for a given post type.
  *
@@ -46,31 +66,3 @@ export function resolveCardComponent(
   const override = themeComponents?.[key] as FC<TimelineCardProps> | undefined;
   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: FC<ThreadPreviewProps>,
-  themeComponents?: ThemeComponents,
-): FC<ThreadPreviewProps> {
-  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: FC<TimelineFeedProps>,
-  themeComponents?: ThemeComponents,
-): FC<TimelineFeedProps> {
-  return themeComponents?.TimelineFeed ?? defaultComponent;
-}

package/src/lib/view.ts

@@ -0,0 +1,318 @@
+/**
+ * View Model Conversions
+ *
+ * Transforms raw database models into render-ready View types.
+ * Theme components receive only View types — no lib/ imports needed.
+ */
+
+import type { Context } from "hono";
+import type {
+  Post,
+  PostWithMedia,
+  Media,
+  MediaView,
+  PostView,
+  NavLinkView,
+  NavigationLink,
+  SearchResult,
+  SearchResultView,
+  ArchiveGroup,
+} from "../types.js";
+import { encode } from "./sqid.js";
+import { toISOString, formatDate } from "./time.js";
+import { getMediaUrl, getImageUrl, getPublicUrlForProvider } from "./image.js";
+
+// =============================================================================
+// Media Context
+// =============================================================================
+
+/**
+ * Central media config — extracted once per request from env.
+ */
+export interface MediaContext {
+  r2PublicUrl?: string;
+  imageTransformUrl?: string;
+  s3PublicUrl?: string;
+}
+
+/**
+ * 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: Context): MediaContext {
+  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: Media, ctx: MediaContext): MediaView {
+  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: PostWithMedia, ctx: MediaContext): PostView {
+  const permalink = `/p/${encode(post.id)}`;
+
+  // Pre-compute excerpt from raw content
+  let excerpt: string | undefined;
+  if (post.content) {
+    excerpt =
+      post.content.length > 160
+        ? post.content.slice(0, 160) + "..."
+        : post.content;
+  }
+
+  // Convert media attachments
+  const media: MediaView[] = 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: PostWithMedia[],
+  ctx: MediaContext,
+): PostView[] {
+  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: Post, ctx: MediaContext): PostView {
+  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: Post[],
+  ctx: MediaContext,
+): PostView[] {
+  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: NavigationLink,
+  currentPath: string,
+): NavLinkView {
+  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: NavigationLink[],
+  currentPath: string,
+): NavLinkView[] {
+  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: SearchResult,
+  ctx: MediaContext,
+): SearchResultView {
+  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: SearchResult[],
+  ctx: MediaContext,
+): SearchResultView[] {
+  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: Map<string, Post[]>,
+  ctx: MediaContext,
+): ArchiveGroup[] {
+  const groups: ArchiveGroup[] = [];
+  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/src/routes/api/__tests__/timeline.test.ts

@@ -13,7 +13,7 @@ import { createPostService } from "../../../services/post.js";
 import { createMediaService } from "../../../services/media.js";
 import { buildMediaMap } from "../../../lib/media-helpers.js";
 import type { Database } from "../../../db/index.js";
-import type { PostWithMedia, TimelineItemData } from "../../../types.js";
+import type { PostWithMedia } from "../../../types.js";
 
 describe("Timeline data assembly", () => {
   let db: Database;
@@ -50,7 +50,7 @@ describe("Timeline data assembly", () => {
     const mediaMap = buildMediaMap(rawMediaMap);
 
     // Assemble items
-    const items: TimelineItemData[] = posts.map((p) => ({
+    const items = posts.map((p) => ({
       post: { ...p, mediaAttachments: mediaMap.get(p.id) ?? [] },
     }));
 
@@ -102,7 +102,7 @@ describe("Timeline data assembly", () => {
     const rawMediaMap = await mediaService.getByPostIds(postIds);
     const mediaMap = buildMediaMap(rawMediaMap);
 
-    const items: TimelineItemData[] = posts.map((post) => {
+    const items = posts.map((post) => {
       const postWithMedia: PostWithMedia = {
         ...post,
         mediaAttachments: mediaMap.get(post.id) ?? [],

package/src/routes/api/timeline.tsx

@@ -5,12 +5,13 @@
  */
 
 import { Hono } from "hono";
-import type { Bindings, PostWithMedia, TimelineItemData } from "../../types.js";
+import type { Bindings, TimelineItemView } from "../../types.js";
 import type { AppVariables } from "../../app.js";
 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";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
@@ -47,14 +48,12 @@ 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 mediaCtx = createMediaContext(c);
   const mediaMap = buildMediaMap(
     rawMediaMap,
-    r2PublicUrl,
-    imageTransformUrl,
-    s3PublicUrl,
+    mediaCtx.r2PublicUrl,
+    mediaCtx.imageTransformUrl,
+    mediaCtx.s3PublicUrl,
   );
 
   // Get reply counts to identify thread roots
@@ -78,51 +77,59 @@ timelineApiRoutes.get("/", async (c) => {
     previewReplyIds.length > 0
       ? buildMediaMap(
           await c.var.services.media.getByPostIds(previewReplyIds),
-          r2PublicUrl,
-          imageTransformUrl,
-          s3PublicUrl,
+          mediaCtx.r2PublicUrl,
+          mediaCtx.imageTransformUrl,
+          mediaCtx.s3PublicUrl,
         )
       : new Map();
 
-  // Assemble timeline items
-  const items: TimelineItemData[] = displayPosts.map((post) => {
-    const postWithMedia: PostWithMedia = {
-      ...post,
-      mediaAttachments: mediaMap.get(post.id) ?? [],
-    };
+  // Assemble timeline items with View Models
+  const items: TimelineItemView[] = displayPosts.map((post) => {
+    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) => ({
-            ...r,
-            mediaAttachments: previewMediaMap.get(r.id) ?? [],
-          })),
+          replies: toPostViews(
+            previewReplies.map((r) => ({
+              ...r,
+              mediaAttachments: previewMediaMap.get(r.id) ?? [],
+            })),
+            mediaCtx,
+          ),
           totalReplyCount: replyCount,
         },
       };
     }
 
-    return { post: postWithMedia };
+    return { 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 (
-          <ThreadPreview
+          <ResolvedThreadPreview
             rootPost={item.post}
             previewReplies={item.threadPreview.replies}
             totalReplyCount={item.threadPreview.totalReplyCount}
+            theme={theme}
           />
         );
       }
-      return <TimelineItem item={item} />;
+      return <TimelineItem item={item} theme={theme} />;
     })
     .map((jsx) => jsx.toString())
     .join("");