@jant/core 0.3.23 → 0.3.25

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;
-  title: string | null;
+  format: Format;
+  status: Status;
+  featured: number; // 0 | 1
+  pinned: number; // 0 | 1
   path: string | null;
-  content: string | null;
-  contentHtml: string | null;
-  sourceUrl: string | null;
-  sourceName: string | null;
-  sourceDomain: string | null;
+  title: 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;
-  title?: string;
+  format: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
   path?: string;
-  content?: string;
-  sourceUrl?: string;
-  sourceName?: string;
+  title?: string;
+  url?: string;
+  body?: string;
+  quoteText?: string;
+  rating?: number;
+  collectionId?: number;
   replyToId?: number;
   publishedAt?: number;
   mediaIds?: string[];
 }
 
 export interface UpdatePost {
-  type?: PostType;
-  visibility?: Visibility;
-  title?: string | null;
+  format?: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
   path?: string | null;
-  content?: string | null;
-  sourceUrl?: string | null;
-  sourceName?: string | null;
+  title?: 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: "/{path}" if path set, otherwise "/p/{sqid}" */
   permalink: string;
+  /** Custom URL path, if set. Supports multi-level paths (e.g. "2024/my-post") */
+  path?: 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,12 +486,15 @@ export interface ArchiveGroup {
   posts: PostView[];
 }
 
+// =============================================================================
+// Page-Based Pagination Types
+// =============================================================================
+
 // =============================================================================
 // Configuration Types
 // =============================================================================
 
-import type { FC, PropsWithChildren } from "hono/jsx";
-import type { ColorTheme } from "./theme/color-themes.js";
+import type { ColorTheme } from "./ui/color-themes.js";
 
 /**
  * Search result from FTS5
@@ -430,8 +513,11 @@ export interface SearchResult {
 
 export interface SiteLayoutProps {
   siteName: string;
-  links: NavLinkView[];
+  siteDescription?: string;
+  links: NavItemView[];
   currentPath: string;
+  isAuthenticated?: boolean;
+  collections?: Collection[];
 }
 
 // =============================================================================
@@ -441,21 +527,24 @@ export interface SiteLayoutProps {
 /** Props for the home page component */
 export interface HomePageProps {
   items: TimelineItemView[];
-  hasMore: boolean;
-  nextCursor?: number;
-  theme?: ThemeComponents;
+  pinnedItems: PostView[];
+  currentPage: number;
+  totalPages: number;
 }
 
 /** Props for the single post page component */
 export interface PostPageProps {
   post: PostView;
-  theme?: ThemeComponents;
 }
 
 /** Props for the custom page component */
 export interface SinglePageProps {
-  page: PostView;
-  theme?: ThemeComponents;
+  page: PageView;
+}
+
+/** Props for the featured page component */
+export interface FeaturedPageProps {
+  items: TimelineItemView[];
 }
 
 /** Props for the archive page component */
@@ -463,8 +552,8 @@ export interface ArchivePageProps {
   groups: ArchiveGroup[];
   hasMore: boolean;
   nextCursor?: number;
-  type?: PostType;
-  theme?: ThemeComponents;
+  format?: Format;
+  featured?: boolean;
 }
 
 /** Props for the search page component */
@@ -474,14 +563,19 @@ export interface SearchPageProps {
   error?: string;
   hasMore: boolean;
   page: number;
-  theme?: ThemeComponents;
 }
 
-/** Props for the collection page component */
+/** Props for the single collection page component */
 export interface CollectionPageProps {
   collection: Collection;
   posts: PostView[];
-  theme?: ThemeComponents;
+  hasMore: boolean;
+  nextCursor?: number;
+}
+
+/** Props for the collections list page component */
+export interface CollectionsPageProps {
+  collections: (Collection & { postCount: number })[];
 }
 
 // =============================================================================
@@ -501,6 +595,7 @@ export interface FeedData {
 export interface SitemapData {
   siteUrl: string;
   posts: PostView[];
+  pages: PageView[];
 }
 
 // =============================================================================
@@ -518,105 +613,13 @@ export interface ThreadPreviewProps {
   rootPost: PostView;
   previewReplies: PostView[];
   totalReplyCount: number;
-  theme?: ThemeComponents;
 }
 
 /** Props for the timeline feed wrapper */
 export interface TimelineFeedProps {
   items: TimelineItemView[];
-  hasMore: boolean;
-  nextCursor?: number;
-  theme?: ThemeComponents;
-}
-
-/**
- * Theme component overrides
- */
-export interface ThemeComponents {
-  // Layout
-  SiteLayout?: FC<PropsWithChildren<SiteLayoutProps>>;
-
-  // Pages
-  HomePage?: FC<HomePageProps>;
-  PostPage?: FC<PostPageProps>;
-  SinglePage?: FC<SinglePageProps>;
-  ArchivePage?: FC<ArchivePageProps>;
-  SearchPage?: FC<SearchPageProps>;
-  CollectionPage?: FC<CollectionPageProps>;
-
-  // Timeline sub-components
-  NoteCard?: FC<TimelineCardProps>;
-  ArticleCard?: FC<TimelineCardProps>;
-  LinkCard?: FC<TimelineCardProps>;
-  QuoteCard?: FC<TimelineCardProps>;
-  ImageCard?: FC<TimelineCardProps>;
-  ThreadPreview?: FC<ThreadPreviewProps>;
-  TimelineFeed?: FC<TimelineFeedProps>;
-
-  // Shared sub-components (re-exported real prop types from component files)
-  Pagination?: FC<PaginationComponentProps>;
-  PagePagination?: FC<PagePaginationComponentProps>;
-  EmptyState?: FC<EmptyStateComponentProps>;
-  MediaGallery?: FC<MediaGalleryComponentProps>;
-}
-
-/**
- * Real component prop types (re-exported from component files via index.ts).
- * These are provided here as aliases to avoid circular imports in types.ts.
- * The canonical definitions live in the component files.
- */
-
-/** @see Pagination component in theme/components/Pagination.tsx */
-export interface PaginationComponentProps {
-  baseUrl: string;
-  hasMore: boolean;
-  nextCursor?: number | string;
-  prevCursor?: number | string;
-  cursorParam?: string;
-}
-
-/** @see PagePagination component in theme/components/Pagination.tsx */
-export interface PagePaginationComponentProps {
-  baseUrl: string;
-  currentPage: number;
-  hasMore: boolean;
-  pageParam?: string;
-}
-
-/** @see EmptyState component in theme/components/EmptyState.tsx */
-export interface EmptyStateComponentProps {
-  message: string;
-  ctaText?: string;
-  ctaHref?: string;
-  centered?: boolean;
-}
-
-/** @see MediaGallery component in theme/components/MediaGallery.tsx */
-export interface MediaGalleryComponentProps {
-  attachments: MediaView[];
-}
-
-/**
- * Theme configuration
- */
-export interface JantTheme {
-  /** Theme name */
-  name?: string;
-  /** Component overrides */
-  components?: ThemeComponents;
-  /** Feed renderer overrides (RSS, Atom, Sitemap) */
-  feed?: {
-    /** Custom RSS 2.0 renderer — returns XML string */
-    rss?: (data: FeedData) => string;
-    /** Custom Atom renderer — returns XML string */
-    atom?: (data: FeedData) => string;
-    /** Custom Sitemap renderer — returns XML string */
-    sitemap?: (data: SitemapData) => string;
-  };
-  /** CSS variable overrides (highest priority, always applied) */
-  cssVariables?: Record<string, string>;
-  /** Replace built-in color themes with a custom list */
-  colorThemes?: ColorTheme[];
+  currentPage?: number;
+  totalPages?: number;
 }
 
 /**
@@ -624,12 +627,23 @@ export interface JantTheme {
  *
  * Configuration Philosophy:
  * - Use environment variables for runtime config (API keys, feature flags, site settings)
- * - Use code config (this object) for compile-time customization (theme components)
+ * - Use code config (this object) for CSS customization and feed overrides
  *
  * Site-level settings (name, description, language) are configured via
  * environment variables, not here. See lib/config.ts for details.
  */
 export interface JantConfig {
-  /** Theme configuration (components, CSS overrides) */
-  theme?: JantTheme;
+  /** CSS variable overrides (highest priority after custom CSS) */
+  cssVariables?: Record<string, string>;
+  /** Replace built-in color themes with custom list */
+  colorThemes?: ColorTheme[];
+  /** Custom feed renderers */
+  feed?: {
+    /** Custom RSS 2.0 renderer -- returns XML string */
+    rss?: (data: FeedData) => string;
+    /** Custom Atom renderer -- returns XML string */
+    atom?: (data: FeedData) => string;
+    /** Custom Sitemap renderer -- returns XML string */
+    sitemap?: (data: SitemapData) => string;
+  };
 }