@jant/core 0.3.22 → 0.3.24

package/src/types.ts

@@ -1,48 +1,34 @@
 /**
- * Jant Type Definitions
+ * Jant Type Definitions (v2)
  */
 
 // =============================================================================
 // Content Types
 // =============================================================================
 
-export const POST_TYPES = [
-  "note",
-  "article",
-  "link",
-  "quote",
-  "image",
-  "page",
+export const FORMATS = ["note", "link", "quote"] as const;
+export type Format = (typeof FORMATS)[number];
+
+export const STATUSES = ["draft", "published"] as const;
+export type Status = (typeof STATUSES)[number];
+
+export const SORT_ORDERS = [
+  "newest",
+  "oldest",
+  "rating_desc",
+  "rating_asc",
 ] as const;
-export type PostType = (typeof POST_TYPES)[number];
+export type SortOrder = (typeof SORT_ORDERS)[number];
 
-export const MAX_MEDIA_ATTACHMENTS = 20;
+export const NAV_ITEM_TYPES = ["page", "link"] as const;
+export type NavItemType = (typeof NAV_ITEM_TYPES)[number];
 
-/**
- * Media attachment rules per post type.
- * Each entry is [min, max] or null (no media allowed).
- */
-export const POST_TYPE_MEDIA_RULES: Record<PostType, [number, number] | null> =
-  {
-    note: [0, 20],
-    article: [0, 20],
-    image: [1, 20],
-    link: [0, 1],
-    quote: [0, 20],
-    page: null,
-  };
+export const MAX_MEDIA_ATTACHMENTS = 20;
+export const MAX_PINNED_POSTS = 3;
 
 export const STORAGE_DRIVERS = ["r2", "s3"] as const;
 export type StorageDriver = (typeof STORAGE_DRIVERS)[number];
 
-export const VISIBILITY_LEVELS = [
-  "featured",
-  "quiet",
-  "unlisted",
-  "draft",
-] as const;
-export type Visibility = (typeof VISIBILITY_LEVELS)[number];
-
 // =============================================================================
 // Cloudflare Bindings
 // =============================================================================
@@ -56,6 +42,8 @@ export interface Bindings {
   IMAGE_TRANSFORM_URL?: string;
   DEMO_EMAIL?: string;
   DEMO_PASSWORD?: string;
+  // Timeline
+  PAGE_SIZE?: string;
   // Site configuration (optional - can be overridden in DB)
   SITE_NAME?: string;
   SITE_DESCRIPTION?: string;
@@ -81,8 +69,8 @@ export interface Bindings {
  * Add new fields here, and they'll automatically work everywhere.
  *
  * Priority logic:
- * - envOnly: false → User-configurable (DB > ENV > Default)
- * - envOnly: true → Environment-only (ENV > Default)
+ * - envOnly: false -> User-configurable (DB > ENV > Default)
+ * - envOnly: true -> Environment-only (ENV > Default)
  */
 export const CONFIG_FIELDS = {
   // User-configurable (can be modified in dashboard)
@@ -124,6 +112,10 @@ export const CONFIG_FIELDS = {
     defaultValue: "",
     envOnly: true,
   },
+  PAGE_SIZE: {
+    defaultValue: "20",
+    envOnly: true,
+  },
   STORAGE_DRIVER: {
     defaultValue: "r2",
     envOnly: true,
@@ -162,15 +154,18 @@ export type ConfigKey = keyof typeof CONFIG_FIELDS;
 
 export interface Post {
   id: number;
-  type: PostType;
-  visibility: Visibility;
+  format: Format;
+  status: Status;
+  featured: number; // 0 | 1
+  pinned: number; // 0 | 1
+  slug: string | null;
   title: string | null;
-  path: string | null;
-  content: string | null;
-  contentHtml: string | null;
-  sourceUrl: string | null;
-  sourceName: string | null;
-  sourceDomain: string | null;
+  url: string | null;
+  body: string | null;
+  bodyHtml: string | null;
+  quoteText: string | null;
+  rating: number | null;
+  collectionId: number | null;
   replyToId: number | null;
   threadId: number | null;
   deletedAt: number | null;
@@ -179,6 +174,17 @@ export interface Post {
   updatedAt: number;
 }
 
+export interface Page {
+  id: number;
+  slug: string;
+  title: string | null;
+  body: string | null;
+  bodyHtml: string | null;
+  status: Status;
+  createdAt: number;
+  updatedAt: number;
+}
+
 export interface Media {
   id: string; // UUIDv7
   postId: number | null;
@@ -214,17 +220,26 @@ export interface PostWithMedia extends Post {
 
 export interface Collection {
   id: number;
+  slug: string;
   title: string;
-  path: string | null;
   description: string | null;
+  icon: string | null;
+  sortOrder: SortOrder;
+  position: number;
+  showDivider: number; // 0 | 1
   createdAt: number;
   updatedAt: number;
 }
 
-export interface PostCollection {
-  postId: number;
-  collectionId: number;
-  addedAt: number;
+export interface NavItem {
+  id: number;
+  type: NavItemType;
+  label: string;
+  url: string;
+  pageId: number | null;
+  position: number;
+  createdAt: number;
+  updatedAt: number;
 }
 
 export interface Redirect {
@@ -241,54 +256,91 @@ export interface Setting {
   updatedAt: number;
 }
 
-export interface NavigationLink {
-  id: number;
-  label: string;
-  url: string;
-  position: number;
-  createdAt: number;
-  updatedAt: number;
-}
-
 // =============================================================================
 // Operation Types
 // =============================================================================
 
 export interface CreatePost {
-  type: PostType;
-  visibility?: Visibility;
+  format: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
+  slug?: string;
   title?: string;
-  path?: string;
-  content?: string;
-  sourceUrl?: string;
-  sourceName?: string;
+  url?: string;
+  body?: string;
+  quoteText?: string;
+  rating?: number;
+  collectionId?: number;
   replyToId?: number;
   publishedAt?: number;
   mediaIds?: string[];
 }
 
 export interface UpdatePost {
-  type?: PostType;
-  visibility?: Visibility;
+  format?: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
+  slug?: string | null;
   title?: string | null;
-  path?: string | null;
-  content?: string | null;
-  sourceUrl?: string | null;
-  sourceName?: string | null;
+  url?: string | null;
+  body?: string | null;
+  quoteText?: string | null;
+  rating?: number | null;
+  collectionId?: number | null;
   publishedAt?: number;
   mediaIds?: string[];
 }
 
-export interface CreateNavigationLink {
+export interface CreatePage {
+  slug: string;
+  title?: string;
+  body?: string;
+  status?: Status;
+}
+
+export interface UpdatePage {
+  slug?: string;
+  title?: string | null;
+  body?: string | null;
+  status?: Status;
+}
+
+export interface CreateNavItem {
+  type: NavItemType;
   label: string;
   url: string;
+  pageId?: number;
   position?: number;
 }
 
-export interface UpdateNavigationLink {
+export interface UpdateNavItem {
+  type?: NavItemType;
   label?: string;
   url?: string;
+  pageId?: number | null;
+  position?: number;
+}
+
+export interface CreateCollection {
+  slug: string;
+  title: string;
+  description?: string;
+  icon?: string;
+  sortOrder?: SortOrder;
   position?: number;
+  showDivider?: boolean;
+}
+
+export interface UpdateCollection {
+  slug?: string;
+  title?: string;
+  description?: string | null;
+  icon?: string | null;
+  sortOrder?: SortOrder;
+  position?: number;
+  showDivider?: boolean;
 }
 
 // =============================================================================
@@ -297,41 +349,54 @@ export interface UpdateNavigationLink {
 
 /**
  * Render-ready post data for theme components.
- * All fields are pre-computed — no lib/ imports needed.
+ * All fields are pre-computed -- no lib/ imports needed.
  */
 export interface PostView {
   // Identity
   id: number;
-  /** Pre-computed permalink, e.g. "/p/jR3k" */
+  /** Pre-computed permalink: "/{slug}" if slug set, otherwise "/p/{sqid}" */
   permalink: string;
+  /** Custom URL slug, if set */
+  slug?: string;
 
   // Content
   title?: string;
   /** Pre-sanitized HTML */
-  contentHtml?: string;
+  bodyHtml?: string;
   /** Pre-computed excerpt, max 160 chars */
   excerpt?: string;
+  /** HTML excerpt for article previews (paragraph-aware, ~500 chars) */
+  summaryHtml?: string;
+  /** Whether summaryHtml was truncated (content continues beyond excerpt) */
+  summaryHasMore?: boolean;
+  /** URL for link/quote formats */
+  url?: string;
+  /** Quoted text for quote format */
+  quoteText?: string;
 
   // Metadata
-  type: PostType;
-  visibility: Visibility;
-  /** Custom path for pages, e.g. "/about" */
-  path?: string;
+  format: Format;
+  status: Status;
+  featured: boolean;
+  pinned: boolean;
+  rating?: number;
+
+  // Collection
+  collectionId?: number;
 
-  // Time — pre-formatted
+  // Time -- pre-formatted
   /** ISO 8601 string */
   publishedAt: string;
   /** Human-readable, e.g. "Feb 1, 2024" */
   publishedAtFormatted: string;
+  /** 24-hour time, e.g. "23:05" */
+  publishedAtTime: string;
+  /** Short relative time, e.g. "5m", "3h", "2d", "Feb 1" */
+  publishedAtRelative: string;
   /** ISO 8601 string */
   updatedAt: string;
 
-  // Source (for link/quote types)
-  sourceUrl?: string;
-  sourceName?: string;
-  sourceDomain?: string;
-
-  // Media — URLs pre-computed
+  // Media -- URLs pre-computed
   media: MediaView[];
 
   // Thread context
@@ -339,12 +404,25 @@ export interface PostView {
   threadRootId?: number;
 
   // Raw content (for forms/editing, not typical theme use)
-  content?: string;
+  body?: string;
+}
+
+/**
+ * Render-ready page data for theme components.
+ */
+export interface PageView {
+  id: number;
+  slug: string;
+  title?: string;
+  bodyHtml?: string;
+  status: Status;
+  createdAt: string;
+  updatedAt: string;
 }
 
 /**
  * Render-ready media data for theme components.
- * URLs are pre-computed — no lib/ imports needed.
+ * URLs are pre-computed -- no lib/ imports needed.
  */
 export interface MediaView {
   id: string;
@@ -360,13 +438,15 @@ export interface MediaView {
 }
 
 /**
- * Render-ready navigation link for theme components.
+ * Render-ready navigation item for theme components.
  * Active/external state pre-computed.
  */
-export interface NavLinkView {
+export interface NavItemView {
   id: number;
+  type: NavItemType;
   label: string;
   url: string;
+  pageId?: number;
   /** Pre-computed based on currentPath */
   isActive: boolean;
   /** Pre-computed: starts with http(s):// */
@@ -406,6 +486,40 @@ export interface ArchiveGroup {
   posts: PostView[];
 }
 
+// =============================================================================
+// Timeline Load-More Types
+// =============================================================================
+
+/** A date-based group of timeline items (shared utility type) */
+export interface DateGroup {
+  dateKey: string;
+  label: string;
+  items: TimelineItemView[];
+}
+
+/** A single SSE DOM patch instruction returned by timelineMore */
+export interface TimelinePatch {
+  selector: string;
+  content: string;
+  mode?:
+    | "append"
+    | "prepend"
+    | "inner"
+    | "outer"
+    | "before"
+    | "after"
+    | "remove";
+}
+
+/** Props passed to the theme's timelineMore renderer */
+export interface TimelineMoreProps {
+  items: TimelineItemView[];
+  lastDate?: string;
+  hasMore: boolean;
+  nextCursor?: number;
+  theme?: ThemeComponents;
+}
+
 // =============================================================================
 // Configuration Types
 // =============================================================================
@@ -430,7 +544,7 @@ export interface SearchResult {
 
 export interface SiteLayoutProps {
   siteName: string;
-  links: NavLinkView[];
+  links: NavItemView[];
   currentPath: string;
 }
 
@@ -441,6 +555,7 @@ export interface SiteLayoutProps {
 /** Props for the home page component */
 export interface HomePageProps {
   items: TimelineItemView[];
+  pinnedItems: PostView[];
   hasMore: boolean;
   nextCursor?: number;
   theme?: ThemeComponents;
@@ -454,7 +569,15 @@ export interface PostPageProps {
 
 /** Props for the custom page component */
 export interface SinglePageProps {
-  page: PostView;
+  page: PageView;
+  theme?: ThemeComponents;
+}
+
+/** Props for the featured page component */
+export interface FeaturedPageProps {
+  items: TimelineItemView[];
+  hasMore: boolean;
+  nextCursor?: number;
   theme?: ThemeComponents;
 }
 
@@ -463,7 +586,8 @@ export interface ArchivePageProps {
   groups: ArchiveGroup[];
   hasMore: boolean;
   nextCursor?: number;
-  type?: PostType;
+  format?: Format;
+  featured?: boolean;
   theme?: ThemeComponents;
 }
 
@@ -477,10 +601,18 @@ export interface SearchPageProps {
   theme?: ThemeComponents;
 }
 
-/** Props for the collection page component */
+/** Props for the single collection page component */
 export interface CollectionPageProps {
   collection: Collection;
   posts: PostView[];
+  hasMore: boolean;
+  nextCursor?: number;
+  theme?: ThemeComponents;
+}
+
+/** Props for the collections list page component */
+export interface CollectionsPageProps {
+  collections: (Collection & { postCount: number })[];
   theme?: ThemeComponents;
 }
 
@@ -501,6 +633,7 @@ export interface FeedData {
 export interface SitemapData {
   siteUrl: string;
   posts: PostView[];
+  pages: PageView[];
 }
 
 // =============================================================================
@@ -529,6 +662,14 @@ export interface TimelineFeedProps {
   theme?: ThemeComponents;
 }
 
+/** Props for the timeline load-more button */
+export interface TimelineLoadMoreProps {
+  nextCursor: number;
+  /** Last visible date key (YYYY-MM-DD) for merging groups across pages */
+  lastDate?: string;
+  theme?: ThemeComponents;
+}
+
 /**
  * Theme component overrides
  */
@@ -540,20 +681,21 @@ export interface ThemeComponents {
   HomePage?: FC<HomePageProps>;
   PostPage?: FC<PostPageProps>;
   SinglePage?: FC<SinglePageProps>;
+  FeaturedPage?: FC<FeaturedPageProps>;
   ArchivePage?: FC<ArchivePageProps>;
   SearchPage?: FC<SearchPageProps>;
   CollectionPage?: FC<CollectionPageProps>;
+  CollectionsPage?: FC<CollectionsPageProps>;
 
-  // Timeline sub-components
+  // Timeline sub-components (by format)
   NoteCard?: FC<TimelineCardProps>;
-  ArticleCard?: FC<TimelineCardProps>;
   LinkCard?: FC<TimelineCardProps>;
   QuoteCard?: FC<TimelineCardProps>;
-  ImageCard?: FC<TimelineCardProps>;
   ThreadPreview?: FC<ThreadPreviewProps>;
   TimelineFeed?: FC<TimelineFeedProps>;
+  TimelineLoadMore?: FC<TimelineLoadMoreProps>;
 
-  // Shared sub-components (re-exported real prop types from component files)
+  // Shared sub-components
   Pagination?: FC<PaginationComponentProps>;
   PagePagination?: FC<PagePaginationComponentProps>;
   EmptyState?: FC<EmptyStateComponentProps>;
@@ -606,13 +748,15 @@ export interface JantTheme {
   components?: ThemeComponents;
   /** Feed renderer overrides (RSS, Atom, Sitemap) */
   feed?: {
-    /** Custom RSS 2.0 renderer — returns XML string */
+    /** Custom RSS 2.0 renderer -- returns XML string */
     rss?: (data: FeedData) => string;
-    /** Custom Atom renderer — returns XML string */
+    /** Custom Atom renderer -- returns XML string */
     atom?: (data: FeedData) => string;
-    /** Custom Sitemap renderer — returns XML string */
+    /** Custom Sitemap renderer -- returns XML string */
     sitemap?: (data: SitemapData) => string;
   };
+  /** Renders SSE patches for timeline load-more responses */
+  timelineMore?: (props: TimelineMoreProps) => TimelinePatch[];
   /** CSS variable overrides (highest priority, always applied) */
   cssVariables?: Record<string, string>;
   /** Replace built-in color themes with a custom list */

package/dist/routes/api/timeline.js

@@ -1,120 +0,0 @@
-import { jsx as _jsx } from "hono/jsx/jsx-runtime";
-/**
- * Timeline API Routes
- *
- * Provides load-more functionality for the timeline feed via SSE.
- */ import { Hono } from "hono";
-import { sse } from "../../lib/sse.js";
-import { buildMediaMap } from "../../lib/media-helpers.js";
-import { TimelineItem } from "../../theme/components/timeline/TimelineItem.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)=>{
-    const cursorParam = c.req.query("cursor");
-    const cursor = cursorParam ? parseInt(cursorParam, 10) : undefined;
-    if (!cursor || isNaN(cursor)) {
-        return c.json({
-            error: "cursor parameter required"
-        }, 400);
-    }
-    // Fetch one extra to determine if there are more
-    const posts = await c.var.services.posts.list({
-        visibility: [
-            "featured",
-            "quiet"
-        ],
-        excludeReplies: true,
-        excludeTypes: [
-            "page"
-        ],
-        limit: PAGE_SIZE + 1,
-        cursor
-    });
-    const hasMore = posts.length > PAGE_SIZE;
-    const displayPosts = hasMore ? posts.slice(0, PAGE_SIZE) : posts;
-    if (displayPosts.length === 0) {
-        return sse(c, async (stream)=>{
-            stream.remove("#load-more-container");
-        });
-    }
-    // Build media map
-    const postIds = displayPosts.map((p)=>p.id);
-    const rawMediaMap = await c.var.services.media.getByPostIds(postIds);
-    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);
-    // Get thread previews
-    const threadPreviews = await c.var.services.posts.getThreadPreviews(threadRootIds, 3);
-    // Load media for preview replies
-    const previewReplyIds = [];
-    for (const replies of threadPreviews.values()){
-        for (const reply of replies){
-            previewReplyIds.push(reply.id);
-        }
-    }
-    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 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: postView,
-                threadPreview: {
-                    replies: toPostViews(previewReplies.map((r)=>({
-                            ...r,
-                            mediaAttachments: previewMediaMap.get(r.id) ?? []
-                        })), mediaCtx),
-                    totalReplyCount: replyCount
-                }
-            };
-        }
-        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 /*#__PURE__*/ _jsx(ResolvedThreadPreview, {
-                rootPost: item.post,
-                previewReplies: item.threadPreview.replies,
-                totalReplyCount: item.threadPreview.totalReplyCount,
-                theme: theme
-            });
-        }
-        return /*#__PURE__*/ _jsx(TimelineItem, {
-            item: item,
-            theme: theme
-        });
-    }).map((jsx)=>jsx.toString()).join("");
-    // Determine next cursor
-    const lastPost = displayPosts[displayPosts.length - 1];
-    const nextCursor = hasMore && lastPost ? lastPost.id : undefined;
-    // Build load-more button HTML
-    const loadMoreHtml = nextCursor ? `<div id="load-more-container" class="mt-6 text-center"><button class="btn btn-outline" data-on:click="@get('/api/timeline?cursor=${nextCursor}')">Load more</button></div>` : "";
-    return sse(c, async (stream)=>{
-        // Append new items to the feed
-        stream.patchElements(itemsHtml, {
-            mode: "append",
-            selector: "#timeline-feed"
-        });
-        // Replace or remove the load-more container
-        if (loadMoreHtml) {
-            stream.patchElements(loadMoreHtml);
-        } else {
-            stream.remove("#load-more-container");
-        }
-    });
-});