@jant/core 0.3.25 → 0.3.26

package/src/types/config.ts

@@ -0,0 +1,183 @@
+/**
+ * Configuration System
+ *
+ * Single Source of Truth for all configuration fields.
+ */
+
+import type { ColorTheme } from "../ui/color-themes.js";
+import type { FeedData, SitemapData } from "./views.js";
+
+/**
+ * Configuration Registry - Single Source of Truth
+ *
+ * All available configuration fields with their metadata.
+ * 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)
+ */
+export const CONFIG_FIELDS = {
+  // User-configurable (can be modified in dashboard)
+  SITE_NAME: {
+    defaultValue: "Jant",
+    envOnly: false,
+  },
+  SITE_DESCRIPTION: {
+    defaultValue: "A microblog powered by Jant",
+    envOnly: false,
+  },
+  SITE_LANGUAGE: {
+    defaultValue: "en",
+    envOnly: false,
+  },
+  HOME_DEFAULT_VIEW: {
+    defaultValue: "latest",
+    envOnly: false,
+  },
+
+  // Environment-only (deployment/infrastructure config)
+  SITE_URL: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  AUTH_SECRET: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  R2_PUBLIC_URL: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  IMAGE_TRANSFORM_URL: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  DEMO_EMAIL: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  DEMO_PASSWORD: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  PAGE_SIZE: {
+    defaultValue: "20",
+    envOnly: true,
+  },
+  STORAGE_DRIVER: {
+    defaultValue: "r2",
+    envOnly: true,
+  },
+  S3_ENDPOINT: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  S3_BUCKET: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  S3_ACCESS_KEY_ID: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  S3_SECRET_ACCESS_KEY: {
+    defaultValue: "",
+    envOnly: true,
+  },
+  S3_REGION: {
+    defaultValue: "auto",
+    envOnly: true,
+  },
+  S3_PUBLIC_URL: {
+    defaultValue: "",
+    envOnly: true,
+  },
+
+  // Internal settings (DB-only, not configurable via env or dashboard)
+  THEME: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  CUSTOM_CSS: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  SITE_AVATAR: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  SHOW_HEADER_AVATAR: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  SITE_FAVICON_ICO: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  SITE_FAVICON_APPLE_TOUCH: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  FONT_THEME: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+  TIME_ZONE: {
+    defaultValue: "UTC",
+    envOnly: false,
+  },
+  SITE_FOOTER: {
+    defaultValue: "",
+    envOnly: false,
+  },
+  NOINDEX: {
+    defaultValue: "",
+    envOnly: false,
+  },
+  ONBOARDING_STATUS: {
+    defaultValue: "pending",
+    envOnly: false,
+    internal: true,
+  },
+  PASSWORD_RESET_TOKEN: {
+    defaultValue: "",
+    envOnly: false,
+    internal: true,
+  },
+} as const;
+
+export type ConfigKey = keyof typeof CONFIG_FIELDS;
+
+/**
+ * Main Jant configuration
+ *
+ * Configuration Philosophy:
+ * - Use environment variables for runtime config (API keys, feature flags, site settings)
+ * - 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 {
+  /** 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;
+  };
+}

package/src/types/constants.ts

@@ -0,0 +1,26 @@
+/**
+ * Content Type Constants
+ */
+
+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 SortOrder = (typeof SORT_ORDERS)[number];
+
+export const NAV_ITEM_TYPES = ["page", "link"] as const;
+export type NavItemType = (typeof NAV_ITEM_TYPES)[number];
+
+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];

package/src/types/entities.ts

@@ -0,0 +1,109 @@
+/**
+ * Entity Types (database-level models)
+ */
+
+import type { Format, Status, SortOrder, NavItemType } from "./constants.js";
+
+export interface Post {
+  id: number;
+  format: Format;
+  status: Status;
+  featured: number; // 0 | 1
+  pinned: number; // 0 | 1
+  path: 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;
+  publishedAt: number;
+  createdAt: number;
+  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;
+  filename: string;
+  originalName: string;
+  mimeType: string;
+  size: number;
+  storageKey: string;
+  provider: string;
+  width: number | null;
+  height: number | null;
+  alt: string | null;
+  position: number;
+  blurhash: string | null;
+  createdAt: number;
+}
+
+export interface MediaAttachment {
+  id: string;
+  url: string;
+  previewUrl: string;
+  alt: string | null;
+  blurhash: string | null;
+  width: number | null;
+  height: number | null;
+  position: number;
+  mimeType: string;
+}
+
+export interface PostWithMedia extends Post {
+  mediaAttachments: MediaAttachment[];
+}
+
+export interface Collection {
+  id: number;
+  slug: string;
+  title: string;
+  description: string | null;
+  icon: string | null;
+  sortOrder: SortOrder;
+  position: number;
+  showDivider: number; // 0 | 1
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface NavItem {
+  id: number;
+  type: NavItemType;
+  label: string;
+  url: string;
+  pageId: number | null;
+  position: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface Redirect {
+  id: number;
+  fromPath: string;
+  toPath: string;
+  type: 301 | 302;
+  createdAt: number;
+}
+
+export interface Setting {
+  key: string;
+  value: string;
+  updatedAt: number;
+}

package/src/types/operations.ts

@@ -0,0 +1,88 @@
+/**
+ * Operation Types (create/update DTOs)
+ */
+
+import type { Format, Status, SortOrder, NavItemType } from "./constants.js";
+
+export interface CreatePost {
+  format: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
+  path?: string;
+  title?: string;
+  url?: string;
+  body?: string;
+  quoteText?: string;
+  rating?: number;
+  collectionId?: number;
+  replyToId?: number;
+  publishedAt?: number;
+  mediaIds?: string[];
+}
+
+export interface UpdatePost {
+  format?: Format;
+  status?: Status;
+  featured?: boolean;
+  pinned?: boolean;
+  path?: 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 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 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;
+}

package/src/types/props.ts

@@ -0,0 +1,115 @@
+/**
+ * Page-Level Props & Feed Data Types
+ */
+
+import type { Format } from "./constants.js";
+import type { Collection } from "./entities.js";
+import type {
+  PostView,
+  PageView,
+  TimelineItemView,
+  SearchResultView,
+  ArchiveGroup,
+} from "./views.js";
+
+// =============================================================================
+// Page-Level Props
+// =============================================================================
+
+/** Props for the home page component */
+export interface HomePageProps {
+  items: TimelineItemView[];
+  pinnedItems: PostView[];
+  currentPage: number;
+  totalPages: number;
+}
+
+/** Props for the single post page component */
+export interface PostPageProps {
+  post: PostView;
+}
+
+/** Props for the custom page component */
+export interface SinglePageProps {
+  page: PageView;
+}
+
+/** Props for the featured page component */
+export interface FeaturedPageProps {
+  items: TimelineItemView[];
+}
+
+/** Props for the archive page component */
+export interface ArchivePageProps {
+  groups: ArchiveGroup[];
+  hasMore: boolean;
+  nextCursor?: number;
+  format?: Format;
+  featured?: boolean;
+}
+
+/** Props for the search page component */
+export interface SearchPageProps {
+  query: string;
+  results: SearchResultView[];
+  error?: string;
+  hasMore: boolean;
+  page: number;
+}
+
+/** Props for the single collection page component */
+export interface CollectionPageProps {
+  collection: Collection;
+  posts: PostView[];
+  hasMore: boolean;
+  nextCursor?: number;
+}
+
+/** Props for the collections list page component */
+export interface CollectionsPageProps {
+  collections: (Collection & { postCount: number })[];
+}
+
+// =============================================================================
+// Feed Data Types
+// =============================================================================
+
+/** Data passed to RSS/Atom feed renderers */
+export interface FeedData {
+  siteName: string;
+  siteDescription: string;
+  siteUrl: string;
+  siteLanguage: string;
+  posts: PostView[];
+}
+
+/** Data passed to sitemap renderers */
+export interface SitemapData {
+  siteUrl: string;
+  posts: PostView[];
+  pages: PageView[];
+}
+
+// =============================================================================
+// Timeline Types
+// =============================================================================
+
+/** Props for per-type timeline cards */
+export interface TimelineCardProps {
+  post: PostView;
+  compact?: boolean;
+}
+
+/** Props for thread inline preview */
+export interface ThreadPreviewProps {
+  rootPost: PostView;
+  previewReplies: PostView[];
+  totalReplyCount: number;
+}
+
+/** Props for the timeline feed wrapper */
+export interface TimelineFeedProps {
+  items: TimelineItemView[];
+  currentPage?: number;
+  totalPages?: number;
+}

package/src/types/views.ts

@@ -0,0 +1,172 @@
+/**
+ * View Model Types (render-ready, for theme components)
+ */
+
+import type { Format, Status, NavItemType } from "./constants.js";
+import type { Post, Collection } from "./entities.js";
+
+/**
+ * Render-ready post data for theme components.
+ * All fields are pre-computed -- no lib/ imports needed.
+ */
+export interface PostView {
+  // Identity
+  id: number;
+  /** 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 */
+  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
+  format: Format;
+  status: Status;
+  featured: boolean;
+  pinned: boolean;
+  rating?: number;
+
+  // Collection
+  collectionId?: number;
+
+  // 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;
+
+  // Media -- URLs pre-computed
+  media: MediaView[];
+
+  // Thread context
+  replyToId?: number;
+  threadRootId?: number;
+
+  // Raw content (for forms/editing, not typical theme use)
+  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.
+ */
+export interface MediaView {
+  id: string;
+  /** Full-size URL, pre-computed */
+  url: string;
+  /** Thumbnail URL, pre-computed */
+  thumbnailUrl: string;
+  mimeType: string;
+  altText?: string;
+  width?: number;
+  height?: number;
+  size?: number;
+}
+
+/**
+ * Render-ready navigation item for theme components.
+ * Active/external state pre-computed.
+ */
+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):// */
+  isExternal: boolean;
+}
+
+/**
+ * Search result from FTS5
+ */
+export interface SearchResult {
+  post: Post;
+  /** FTS5 rank score (lower is better) */
+  rank: number;
+  /** Highlighted snippet from content */
+  snippet?: string;
+}
+
+/**
+ * Render-ready search result for theme components.
+ */
+export interface SearchResultView {
+  post: PostView;
+  rank: number;
+  snippet?: string;
+}
+
+/**
+ * Render-ready timeline item for theme components.
+ */
+export interface TimelineItemView {
+  post: PostView;
+  threadPreview?: {
+    replies: PostView[];
+    totalReplyCount: number;
+  };
+}
+
+/**
+ * Typed archive group with pre-formatted label.
+ */
+export interface ArchiveGroup {
+  /** e.g. "2024" */
+  year: string;
+  /** e.g. "02" */
+  month: string;
+  /** Pre-formatted, e.g. "February 2024" */
+  label: string;
+  posts: PostView[];
+}
+
+/**
+ * Site Layout Props
+ */
+export interface SiteLayoutProps {
+  siteName: string;
+  siteDescription?: string;
+  links: NavItemView[];
+  currentPath: string;
+  isAuthenticated?: boolean;
+  collections?: Collection[];
+  homeDefaultView?: string;
+  siteAvatarUrl?: string;
+  showHeaderAvatar?: boolean;
+  siteFooterHtml?: string;
+}