@jant/core 0.3.22 → 0.3.24

package/src/lib/schemas.ts

@@ -1,5 +1,5 @@
 /**
- * Shared Zod schemas for validation
+ * Shared Zod schemas for validation (v2)
  *
  * These schemas ensure type-safe validation of user input
  * from forms, API requests, and other external sources.
@@ -10,24 +10,34 @@
 
 import { z } from "zod";
 import {
-  POST_TYPES,
-  VISIBILITY_LEVELS,
+  FORMATS,
+  STATUSES,
+  SORT_ORDERS,
+  NAV_ITEM_TYPES,
   MAX_MEDIA_ATTACHMENTS,
-  POST_TYPE_MEDIA_RULES,
 } from "../types.js";
-import type { PostType } from "../types.js";
 
 /**
- * Post type enum schema
- * Based on POST_TYPES from types.ts
+ * Post format enum schema
+ * Based on FORMATS from types.ts
  */
-export const PostTypeSchema = z.enum(POST_TYPES);
+export const FormatSchema = z.enum(FORMATS);
 
 /**
- * Visibility enum schema
- * Based on VISIBILITY_LEVELS from types.ts
+ * Post status enum schema
+ * Based on STATUSES from types.ts
  */
-export const VisibilitySchema = z.enum(VISIBILITY_LEVELS);
+export const StatusSchema = z.enum(STATUSES);
+
+/**
+ * Collection sort order enum schema
+ */
+export const SortOrderSchema = z.enum(SORT_ORDERS);
+
+/**
+ * Navigation item type enum schema
+ */
+export const NavItemTypeSchema = z.enum(NAV_ITEM_TYPES);
 
 /**
  * Redirect type enum schema
@@ -35,21 +45,45 @@ export const VisibilitySchema = z.enum(VISIBILITY_LEVELS);
  */
 export const RedirectTypeSchema = z.enum(["301", "302"]);
 
+/**
+ * Rating schema (1-5 integer)
+ */
+export const RatingSchema = z.coerce
+  .number()
+  .int()
+  .min(1)
+  .max(5)
+  .optional()
+  .or(z.literal("").transform(() => undefined));
+
 /**
  * API request body schema for creating a post
  */
 export const CreatePostSchema = z.object({
-  type: PostTypeSchema,
-  title: z.string().optional(),
-  content: z.string(),
-  visibility: VisibilitySchema,
-  sourceUrl: z.url().optional().or(z.literal("")),
-  sourceName: z.string().optional(),
-  path: z
+  format: FormatSchema,
+  slug: z
     .string()
-    .regex(/^[a-z0-9-]*$/)
+    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/)
+    .optional()
+    .or(z.literal("").transform(() => undefined)),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  status: StatusSchema.optional(),
+  featured: z
+    .union([z.boolean(), z.literal("on").transform(() => true)])
+    .optional(),
+  pinned: z
+    .union([z.boolean(), z.literal("on").transform(() => true)])
+    .optional(),
+  url: z.url().optional().or(z.literal("")),
+  quoteText: z.string().optional(),
+  rating: RatingSchema,
+  collectionId: z.coerce
+    .number()
+    .int()
+    .positive()
     .optional()
-    .or(z.literal("")),
+    .or(z.literal("").transform(() => undefined)),
   replyToId: z.string().optional(), // Sqid format
   publishedAt: z.number().int().positive().optional(),
   mediaIds: z.array(z.string()).max(MAX_MEDIA_ATTACHMENTS).optional(),
@@ -60,13 +94,70 @@ export const CreatePostSchema = z.object({
  */
 export const UpdatePostSchema = CreatePostSchema.partial();
 
+/**
+ * API request body schema for creating a page
+ */
+export const CreatePageSchema = z.object({
+  slug: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/),
+  title: z.string().optional(),
+  body: z.string().optional(),
+  status: StatusSchema.optional(),
+});
+
+/**
+ * API request body schema for updating a page
+ */
+export const UpdatePageSchema = CreatePageSchema.partial();
+
+/**
+ * API request body schema for creating a navigation item
+ */
+export const CreateNavItemSchema = z.object({
+  type: NavItemTypeSchema,
+  label: z.string().min(1),
+  url: z.string().min(1),
+  pageId: z.coerce.number().int().positive().optional(),
+  position: z.coerce.number().int().min(0).optional(),
+});
+
+/**
+ * API request body schema for updating a navigation item
+ */
+export const UpdateNavItemSchema = CreateNavItemSchema.partial();
+
+/**
+ * API request body schema for creating a collection
+ */
+export const CreateCollectionSchema = z.object({
+  slug: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+  sortOrder: SortOrderSchema.optional(),
+  position: z.coerce.number().int().min(0).optional(),
+  showDivider: z
+    .union([z.boolean(), z.literal("on").transform(() => true)])
+    .optional(),
+});
+
+/**
+ * API request body schema for updating a collection
+ */
+export const UpdateCollectionSchema = CreateCollectionSchema.partial();
+
 /**
  * Form data helper: safely parse a FormData value with a schema
  *
  * @example
  * ```ts
- * const type = parseFormData(formData, "type", PostTypeSchema);
- * // type is PostType, throws if invalid
+ * const format = parseFormData(formData, "format", FormatSchema);
+ * // format is Format, throws if invalid
  * ```
  */
 export function parseFormData<T>(
@@ -103,40 +194,15 @@ export function parseFormDataOptional<T>(
 }
 
 /**
- * Validates media attachment count against post type rules.
+ * Validates media attachment count for a post.
+ * All formats allow 0-20 media attachments.
  *
- * @param type - The post type to validate against
  * @param mediaIds - Array of media IDs to attach
  * @returns null if valid, error string if invalid
- *
- * @example
- * ```ts
- * const error = validateMediaForPostType("image", []);
- * // Returns: "image posts require at least 1 media attachment"
- * ```
  */
-export function validateMediaForPostType(
-  type: PostType,
-  mediaIds: string[],
-): string | null {
-  const rules = POST_TYPE_MEDIA_RULES[type];
-
-  if (rules === null) {
-    if (mediaIds.length > 0) {
-      return `${type} posts do not allow media attachments`;
-    }
-    return null;
+export function validateMediaCount(mediaIds: string[]): string | null {
+  if (mediaIds.length > MAX_MEDIA_ATTACHMENTS) {
+    return `Posts allow at most ${MAX_MEDIA_ATTACHMENTS} media attachments`;
   }
-
-  const [min, max] = rules;
-
-  if (mediaIds.length < min) {
-    return `${type} posts require at least ${min} media attachment${min !== 1 ? "s" : ""}`;
-  }
-
-  if (mediaIds.length > max) {
-    return `${type} posts allow at most ${max} media attachment${max !== 1 ? "s" : ""}`;
-  }
-
   return null;
 }

package/src/lib/theme-components.ts

@@ -5,15 +5,12 @@
  */
 
 import type { FC } from "hono/jsx";
-import type { PostType, ThemeComponents, TimelineCardProps } from "../types.js";
+import type { Format, ThemeComponents, TimelineCardProps } from "../types.js";
 
-const THEME_KEY_MAP: Record<PostType, keyof ThemeComponents> = {
+const THEME_KEY_MAP: Record<Format, keyof ThemeComponents> = {
   note: "NoteCard",
-  article: "ArticleCard",
   link: "LinkCard",
   quote: "QuoteCard",
-  image: "ImageCard",
-  page: "NoteCard",
 };
 
 /**
@@ -43,26 +40,26 @@ export function resolveComponent<K extends keyof ThemeComponents>(
 }
 
 /**
- * Resolves the card component for a given post type.
+ * Resolves the card component for a given post format.
  *
  * Checks theme overrides first, then falls back to the provided default card component.
  *
- * @param type - The post type to resolve a card for
- * @param defaults - Map of post type to default card component
+ * @param format - The post format to resolve a card for
+ * @param defaults - Map of format to default card component
  * @param themeComponents - Optional theme component overrides
  * @returns The resolved card component
  *
  * @example
  * ```ts
- * const Card = resolveCardComponent("article", DEFAULT_CARD_MAP, c.var.config.theme?.components);
+ * const Card = resolveCardComponent("note", DEFAULT_CARD_MAP, c.var.config.theme?.components);
  * ```
  */
 export function resolveCardComponent(
-  type: PostType,
-  defaults: Record<PostType, FC<TimelineCardProps>>,
+  format: Format,
+  defaults: Record<Format, FC<TimelineCardProps>>,
   themeComponents?: ThemeComponents,
 ): FC<TimelineCardProps> {
-  const key = THEME_KEY_MAP[type];
+  const key = THEME_KEY_MAP[format];
   const override = themeComponents?.[key] as FC<TimelineCardProps> | undefined;
-  return override ?? defaults[type];
+  return override ?? defaults[format];
 }

package/src/lib/time.ts

@@ -109,6 +109,70 @@ export function formatDate(timestamp: number): string {
  * // Returns: "2024-02"
  * ```
  */
+/**
+ * Formats a Unix timestamp as a 24-hour time string (HH:MM).
+ *
+ * Converts a Unix timestamp (in seconds) to a zero-padded time string in
+ * 24-hour format. Always uses UTC timezone for consistency.
+ *
+ * @param timestamp - Unix timestamp in seconds to format
+ * @returns Formatted time string in "HH:MM" format
+ *
+ * @example
+ * ```ts
+ * const time = formatTime(1706745600);
+ * // Returns: "00:00"
+ * ```
+ */
+export function formatTime(timestamp: number): string {
+  const date = new Date(timestamp * 1000);
+  const hours = String(date.getUTCHours()).padStart(2, "0");
+  const minutes = String(date.getUTCMinutes()).padStart(2, "0");
+  return `${hours}:${minutes}`;
+}
+
+/**
+ * Formats a Unix timestamp as a short relative time string.
+ *
+ * Returns compact labels like "1m", "5h", "3d" for recent timestamps,
+ * and falls back to "MMM D" (e.g. "Feb 1") for anything older than 7 days.
+ *
+ * @param timestamp - Unix timestamp in seconds
+ * @returns Short relative time string
+ *
+ * @example
+ * ```ts
+ * // Assuming current time is Feb 16, 2026
+ * formatRelativeTime(now() - 30);       // "1m"  (30 seconds → rounds up)
+ * formatRelativeTime(now() - 3600);     // "1h"
+ * formatRelativeTime(now() - 86400);    // "1d"
+ * formatRelativeTime(now() - 604800);   // "7d"
+ * formatRelativeTime(now() - 864000);   // "Feb 6"
+ * ```
+ */
+export function formatRelativeTime(timestamp: number): string {
+  const seconds = now() - timestamp;
+
+  if (seconds < 60) return "1m";
+
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+
+  const hours = Math.floor(seconds / 3600);
+  if (hours < 24) return `${hours}h`;
+
+  const days = Math.floor(seconds / 86400);
+  if (days <= 7) return `${days}d`;
+
+  // Older than 7 days: show "MMM D" (e.g. "Feb 1")
+  const date = new Date(timestamp * 1000);
+  return date.toLocaleDateString("en-US", {
+    month: "short",
+    day: "numeric",
+    timeZone: "UTC",
+  });
+}
+
 export function formatYearMonth(timestamp: number): string {
   const date = new Date(timestamp * 1000);
   const year = date.getUTCFullYear();

package/src/lib/timeline.ts

@@ -0,0 +1,170 @@
+/**
+ * Timeline Data Assembly
+ *
+ * Shared helper for assembling timeline items with media and thread previews.
+ * Used by both full-page rendering and load-more SSE responses.
+ */
+
+import type { Context } from "hono";
+import type { Bindings, TimelineItemView, DateGroup } from "../types.js";
+import type { AppVariables } from "../app.js";
+import { buildMediaMap } from "./media-helpers.js";
+import { createMediaContext, toPostView, toPostViews } from "./view.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+const DEFAULT_PAGE_SIZE = 20;
+
+/**
+ * Result from assembling a timeline page.
+ */
+export interface TimelineResult {
+  items: TimelineItemView[];
+  hasMore: boolean;
+  nextCursor?: number;
+}
+
+/**
+ * Assembles a page of timeline items with media attachments and thread previews.
+ *
+ * Fetches posts, batch-loads media, identifies threads, and returns
+ * render-ready `TimelineItemView[]` with pagination info.
+ *
+ * @param c - Hono context (provides services + env)
+ * @param options - Optional cursor for pagination
+ * @returns Assembled timeline items with pagination info
+ *
+ * @example
+ * ```ts
+ * const { items, hasMore, nextCursor } = await assembleTimeline(c);
+ * const { items, hasMore, nextCursor } = await assembleTimeline(c, { cursor: 42 });
+ * ```
+ */
+export async function assembleTimeline(
+  c: Context<Env>,
+  options?: { cursor?: number },
+): Promise<TimelineResult> {
+  const pageSize =
+    parseInt(c.env.PAGE_SIZE ?? String(DEFAULT_PAGE_SIZE), 10) ||
+    DEFAULT_PAGE_SIZE;
+
+  // Fetch one extra to determine if there are more
+  const posts = await c.var.services.posts.list({
+    status: "published",
+    excludeReplies: true,
+    limit: pageSize + 1,
+    cursor: options?.cursor,
+  });
+
+  const hasMore = posts.length > pageSize;
+  const displayPosts = hasMore ? posts.slice(0, pageSize) : posts;
+
+  if (displayPosts.length === 0) {
+    return { items: [], hasMore: false };
+  }
+
+  // Batch load media attachments
+  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);
+
+  // Batch load thread previews
+  const threadPreviews = await c.var.services.posts.getThreadPreviews(
+    threadRootIds,
+    3,
+  );
+
+  // Batch load media for preview replies
+  const previewReplyIds: number[] = [];
+  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: 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: postView,
+        threadPreview: {
+          replies: toPostViews(
+            previewReplies.map((r) => ({
+              ...r,
+              mediaAttachments: previewMediaMap.get(r.id) ?? [],
+            })),
+            mediaCtx,
+          ),
+          totalReplyCount: replyCount,
+        },
+      };
+    }
+
+    return { post: postView };
+  });
+
+  // Determine next cursor
+  const lastPost = displayPosts[displayPosts.length - 1];
+  const nextCursor = hasMore && lastPost ? lastPost.id : undefined;
+
+  return { items, hasMore, nextCursor };
+}
+
+/**
+ * Groups timeline items by their publication date (YYYY-MM-DD).
+ *
+ * @param items - Timeline items to group
+ * @returns Array of date groups, each containing items published on the same day
+ *
+ * @example
+ * ```ts
+ * const groups = groupByDate(items);
+ * // [{ dateKey: "2024-02-01", label: "Feb 1, 2024", items: [...] }, ...]
+ * ```
+ */
+export function groupByDate(items: TimelineItemView[]): DateGroup[] {
+  const groups: DateGroup[] = [];
+  let current: DateGroup | null = null;
+
+  for (const item of items) {
+    const dateKey = item.post.publishedAt.slice(0, 10);
+    if (!current || current.dateKey !== dateKey) {
+      current = {
+        dateKey,
+        label: item.post.publishedAtFormatted,
+        items: [],
+      };
+      groups.push(current);
+    }
+    current.items.push(item);
+  }
+
+  return groups;
+}