@jant/core 0.3.23 → 0.3.25

package/src/lib/excerpt.ts

@@ -0,0 +1,87 @@
+/**
+ * HTML Excerpt Utilities
+ *
+ * Generates paragraph-aware excerpts from HTML content for article
+ * previews in timelines. Breaks only at paragraph boundaries.
+ */
+
+/**
+ * Strips HTML tags from a string, returning plain text.
+ *
+ * @param html - HTML string to strip
+ * @returns Plain text without HTML tags
+ *
+ * @example
+ * ```typescript
+ * stripHtml("<p>Hello <strong>world</strong></p>") // "Hello world"
+ * ```
+ */
+export function stripHtml(html: string): string {
+  return html.replace(/<[^>]*>/g, "");
+}
+
+/**
+ * Result of extracting an HTML excerpt.
+ */
+export interface HtmlExcerpt {
+  /** HTML excerpt (complete paragraphs only) */
+  excerpt: string;
+  /** Whether the original content has more text beyond the excerpt */
+  hasMore: boolean;
+}
+
+/**
+ * Extracts a paragraph-aware HTML excerpt from body HTML.
+ *
+ * Uses a greedy algorithm: accumulates paragraphs until the total
+ * plain-text length exceeds 500 characters, then stops. At least
+ * one paragraph is always included.
+ *
+ * If the content contains a `<!--more-->` marker, the content before
+ * the marker is used as the excerpt instead.
+ *
+ * @param bodyHtml - Full HTML body content
+ * @returns Excerpt HTML and whether there is more content
+ *
+ * @example
+ * ```typescript
+ * // Short content — returned as-is with hasMore = false
+ * getHtmlExcerpt("<p>Short post.</p>")
+ * // { excerpt: "<p>Short post.</p>", hasMore: false }
+ *
+ * // Long content — truncated at paragraph boundary
+ * getHtmlExcerpt("<p>" + "A".repeat(300) + "</p><p>" + "B".repeat(300) + "</p>")
+ * // { excerpt: "<p>AAA...</p>", hasMore: true }
+ *
+ * // Manual break with <!--more-->
+ * getHtmlExcerpt("<p>Intro</p><!--more--><p>Rest</p>")
+ * // { excerpt: "<p>Intro</p>", hasMore: true }
+ * ```
+ */
+export function getHtmlExcerpt(bodyHtml: string): HtmlExcerpt {
+  // Honor manual <!--more--> marker
+  if (bodyHtml.includes("<!--more-->")) {
+    const excerpt = bodyHtml.split("<!--more-->")[0]!;
+    return { excerpt, hasMore: true };
+  }
+
+  const paragraphs = bodyHtml.match(/<p>[\s\S]*?<\/p>/g) || [];
+
+  // No paragraphs found — return full content
+  if (paragraphs.length === 0) {
+    return { excerpt: bodyHtml, hasMore: false };
+  }
+
+  let excerpt = "";
+  let charCount = 0;
+
+  for (const p of paragraphs) {
+    const textLen = stripHtml(p).length;
+    if (charCount + textLen > 500 && excerpt) break;
+    excerpt += p;
+    charCount += textLen;
+  }
+
+  const hasMore = excerpt.length < bodyHtml.length;
+  return { excerpt, hasMore };
+}

package/src/lib/feed.ts

@@ -51,7 +51,7 @@ export function defaultRssRenderer(data: FeedData): string {
       <link>${link}</link>
       <guid isPermaLink="true">${link}</guid>
       <pubDate>${pubDate}</pubDate>
-      <description><![CDATA[${post.contentHtml || ""}]]></description>${enclosure}
+      <description><![CDATA[${post.bodyHtml || ""}]]></description>${enclosure}
     </item>`;
     })
     .join("");
@@ -90,7 +90,7 @@ export function defaultAtomRenderer(data: FeedData): string {
     <id>${link}</id>
     <published>${post.publishedAt}</published>
     <updated>${post.updatedAt}</updated>
-    <content type="html"><![CDATA[${post.contentHtml || ""}]]></content>
+    <content type="html"><![CDATA[${post.bodyHtml || ""}]]></content>
   </entry>`;
     })
     .join("");
@@ -112,17 +112,17 @@ export function defaultAtomRenderer(data: FeedData): string {
 /**
  * Default Sitemap renderer.
  *
- * @param data - Sitemap data with PostView[] (pre-computed URLs)
+ * @param data - Sitemap data with PostView[] and PageView[]
  * @returns Sitemap XML string
  */
 export function defaultSitemapRenderer(data: SitemapData): string {
-  const { siteUrl, posts } = data;
+  const { siteUrl, posts, pages } = data;
 
-  const urls = posts
+  const postUrls = posts
     .map((post) => {
       const loc = `${siteUrl}${post.permalink}`;
       const lastmod = post.updatedAt.split("T")[0];
-      const priority = post.visibility === "featured" ? "0.8" : "0.6";
+      const priority = post.featured ? "0.8" : "0.6";
 
       return `
   <url>
@@ -133,6 +133,20 @@ export function defaultSitemapRenderer(data: SitemapData): string {
     })
     .join("");
 
+  const pageUrls = pages
+    .map((page) => {
+      const loc = `${siteUrl}/${page.slug}`;
+      const lastmod = page.updatedAt.split("T")[0];
+
+      return `
+  <url>
+    <loc>${loc}</loc>
+    <lastmod>${lastmod}</lastmod>
+    <priority>0.7</priority>
+  </url>`;
+    })
+    .join("");
+
   const homepageUrl = `
   <url>
     <loc>${siteUrl}/</loc>
@@ -143,6 +157,7 @@ export function defaultSitemapRenderer(data: SitemapData): string {
   return `<?xml version="1.0" encoding="UTF-8"?>
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   ${homepageUrl}
-  ${urls}
+  ${postUrls}
+  ${pageUrls}
 </urlset>`;
 }

package/src/lib/nav-reorder.ts

@@ -16,7 +16,7 @@ if (list) {
       const ids = [...list.querySelectorAll<HTMLElement>("[data-id]")].map(
         (el) => Number(el.dataset.id),
       );
-      fetch("/dash/navigation/reorder", {
+      fetch("/dash/pages/reorder", {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ ids }),

package/src/lib/navigation.ts

@@ -6,23 +6,26 @@
 
 import type { Context } from "hono";
 import { getSiteName } from "./config.js";
-import type { NavLinkView } from "../types.js";
-import { toNavLinkViews } from "./view.js";
+import type { Collection, NavItemView } from "../types.js";
+import { toNavItemViews } from "./view.js";
 
 /**
  * Navigation data needed by SiteLayout
  */
 export interface NavigationData {
-  links: NavLinkView[];
+  links: NavItemView[];
   currentPath: string;
   siteName: string;
+  siteDescription: string;
+  isAuthenticated: boolean;
+  collections: Collection[];
 }
 
 /**
  * Fetch navigation data for public pages.
  *
- * Ensures default links exist (Home, Archive, RSS) and returns
- * NavLinkView[] with pre-computed isActive/isExternal state.
+ * Returns NavItemView[] with pre-computed isActive/isExternal state.
+ * Also checks authentication status and loads collections for authenticated users.
  *
  * @param c - Hono context
  * @returns Navigation data for SiteLayout
@@ -38,9 +41,43 @@ export interface NavigationData {
  * ```
  */
 export async function getNavigationData(c: Context): Promise<NavigationData> {
-  const navigationLinks = await c.var.services.navigationLinks.ensureDefaults();
+  const items = await c.var.services.navItems.list();
   const currentPath = new URL(c.req.url).pathname;
   const siteName = await getSiteName(c);
-  const links = toNavLinkViews(navigationLinks, currentPath);
-  return { links, currentPath, siteName };
+
+  // Only include description if explicitly set (DB or env), not the default
+  const dbDescription = await c.var.services.settings.get("SITE_DESCRIPTION");
+  const envDescription = c.env.SITE_DESCRIPTION;
+  const siteDescription =
+    dbDescription || (typeof envDescription === "string" ? envDescription : "");
+
+  const links = toNavItemViews(items, currentPath);
+
+  // Check auth status for compose button
+  let isAuthenticated = false;
+  let collections: Collection[] = [];
+  if (c.var.auth) {
+    try {
+      const session = await c.var.auth.api.getSession({
+        headers: c.req.raw.headers,
+      });
+      isAuthenticated = !!session?.user;
+    } catch {
+      // Not authenticated
+    }
+  }
+
+  // Only load collections when authenticated (for compose dialog)
+  if (isAuthenticated) {
+    collections = await c.var.services.collections.list();
+  }
+
+  return {
+    links,
+    currentPath,
+    siteName,
+    siteDescription,
+    isAuthenticated,
+    collections,
+  };
 }

package/src/lib/pagination.ts

@@ -0,0 +1,50 @@
+/**
+ * Pagination Utilities
+ *
+ * Pure utility functions for page-based pagination.
+ */
+
+/**
+ * Computes which page numbers to display in a numbered pagination control.
+ * Always includes: first page, last page, current page, and 1 page on each side of current.
+ * Gaps between non-consecutive pages are represented by 0 (ellipsis marker).
+ *
+ * @param currentPage - The current active page (1-indexed)
+ * @param totalPages - Total number of pages
+ * @returns Array of page numbers, with 0 representing ellipsis gaps
+ *
+ * @example
+ * ```ts
+ * getPageNumbers(1, 5)    // [1, 2, 3, 4, 5]
+ * getPageNumbers(1, 20)   // [1, 2, 0, 20]
+ * getPageNumbers(10, 20)  // [1, 0, 9, 10, 11, 0, 20]
+ * ```
+ */
+export function getPageNumbers(
+  currentPage: number,
+  totalPages: number,
+): number[] {
+  if (totalPages <= 7) {
+    return Array.from({ length: totalPages }, (_, i) => i + 1);
+  }
+
+  const pages = new Set<number>();
+  pages.add(1);
+  pages.add(totalPages);
+  pages.add(currentPage);
+  if (currentPage > 1) pages.add(currentPage - 1);
+  if (currentPage < totalPages) pages.add(currentPage + 1);
+
+  const sorted = [...pages].sort((a, b) => a - b);
+
+  // Insert 0 for gaps
+  const result: number[] = [];
+  for (let i = 0; i < sorted.length; i++) {
+    if (i > 0 && sorted[i]! - sorted[i - 1]! > 1) {
+      result.push(0); // ellipsis marker
+    }
+    result.push(sorted[i]!);
+  }
+
+  return result;
+}

package/src/lib/render.tsx

@@ -3,16 +3,13 @@
  *
  * 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 "../themes/minimal/MinimalSiteLayout.js";
+import type { SiteLayoutProps } from "../types.js";
+import { BaseLayout } from "../ui/layouts/BaseLayout.js";
+import { SiteLayout } from "../ui/layouts/SiteLayout.js";
 import type { NavigationData } from "./navigation.js";
 
 export interface RenderPublicPageOptions {
@@ -29,8 +26,6 @@ export interface RenderPublicPageOptions {
 /**
  * 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
@@ -48,20 +43,18 @@ export interface RenderPublicPageOptions {
 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,
+    siteDescription: navData.siteDescription,
     links: navData.links,
     currentPath: navData.currentPath,
+    isAuthenticated: navData.isAuthenticated,
+    collections: navData.collections,
   };
 
   return c.html(
     <BaseLayout title={title} description={description} c={c}>
-      <Layout {...layoutProps}>{content}</Layout>
+      <SiteLayout {...layoutProps}>{content}</SiteLayout>
     </BaseLayout>,
   );
 }

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,47 @@ 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(0)
+  .max(5)
+  .optional()
+  .or(z.literal("").transform(() => undefined))
+  .transform((v) => (v === 0 ? undefined : v));
+
 /**
  * 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(),
+  format: FormatSchema,
   path: z
     .string()
-    .regex(/^[a-z0-9-]*$/)
+    .regex(/^[a-z0-9]([a-z0-9-]*[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()
+    .min(0)
     .optional()
-    .or(z.literal("")),
+    .or(z.literal("").transform(() => undefined))
+    .transform((v) => (v === 0 ? undefined : v)),
   replyToId: z.string().optional(), // Sqid format
   publishedAt: z.number().int().positive().optional(),
   mediaIds: z.array(z.string()).max(MAX_MEDIA_ATTACHMENTS).optional(),
@@ -60,13 +96,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 +196,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.ts

@@ -4,14 +4,14 @@
  * Resolves the active color theme and builds CSS for injection into `<head>`.
  */
 
-import type { ColorTheme } from "../theme/color-themes.js";
-import { BUILTIN_COLOR_THEMES } from "../theme/color-themes.js";
+import type { ColorTheme } from "../ui/color-themes.js";
+import { BUILTIN_COLOR_THEMES } from "../ui/color-themes.js";
 import type { JantConfig } from "../types.js";
 
 /**
  * Get the list of available color themes.
  *
- * Returns `config.theme.colorThemes` if provided, otherwise the built-in list.
+ * Returns `config.colorThemes` if provided, otherwise the built-in list.
  *
  * @param config - The Jant configuration
  * @returns Array of available color themes
@@ -22,7 +22,7 @@ import type { JantConfig } from "../types.js";
  * ```
  */
 export function getAvailableThemes(config: JantConfig): ColorTheme[] {
-  return config.theme?.colorThemes ?? BUILTIN_COLOR_THEMES;
+  return config.colorThemes ?? BUILTIN_COLOR_THEMES;
 }
 
 /**
@@ -32,7 +32,7 @@ export function getAvailableThemes(config: JantConfig): ColorTheme[] {
  *   BaseCoat defaults → selected theme → cssVariables
  *
  * @param theme - The active color theme (undefined = no theme overrides)
- * @param cssVariables - Extra CSS variable overrides from `createApp({ theme: { cssVariables } })`
+ * @param cssVariables - Extra CSS variable overrides from `createApp({ cssVariables })`
  * @returns CSS string to inject in `<head>`, or empty string if nothing to inject
  *
  * Uses `:root:root` and `:root.dark` selectors for higher specificity than

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();