@jant/core 0.3.24 → 0.3.26

package/src/lib/__tests__/timeline.test.ts

@@ -12,9 +12,8 @@ import { createTestDatabase } from "../../__tests__/helpers/db.js";
 import { createPostService } from "../../services/post.js";
 import { createMediaService } from "../../services/media.js";
 import { buildMediaMap } from "../media-helpers.js";
-import { groupByDate } from "../timeline.js";
 import type { Database } from "../../db/index.js";
-import type { PostWithMedia, TimelineItemView } from "../../types.js";
+import type { PostWithMedia } from "../../types.js";
 
 describe("Timeline data assembly", () => {
   let db: Database;
@@ -184,101 +183,66 @@ describe("Timeline data assembly", () => {
     expect(page2.every((p) => p.id < (lastPost?.id ?? 0))).toBe(true);
   });
 
-  it("correctly determines hasMore flag", async () => {
-    for (let i = 0; i < 3; i++) {
+  it("supports offset-based pagination for page navigation", async () => {
+    for (let i = 0; i < 5; i++) {
       await postService.create({
         format: "note",
         body: `Post ${i}`,
+        publishedAt: 1000 + i,
       });
     }
 
-    // Request limit + 1 to check for more
     const pageSize = 2;
-    const posts = await postService.list({
+
+    // Page 1
+    const page1 = await postService.list({
       status: "published",
       excludeReplies: true,
-      limit: pageSize + 1,
+      limit: pageSize,
+      offset: 0,
     });
+    expect(page1).toHaveLength(2);
+    expect(page1[0]?.body).toBe("Post 4");
+    expect(page1[1]?.body).toBe("Post 3");
 
-    const hasMore = posts.length > pageSize;
-    expect(hasMore).toBe(true);
+    // Page 2
+    const page2 = await postService.list({
+      status: "published",
+      excludeReplies: true,
+      limit: pageSize,
+      offset: 2,
+    });
+    expect(page2).toHaveLength(2);
+    expect(page2[0]?.body).toBe("Post 2");
+    expect(page2[1]?.body).toBe("Post 1");
 
-    const displayPosts = posts.slice(0, pageSize);
-    expect(displayPosts).toHaveLength(2);
+    // Page 3 (partial)
+    const page3 = await postService.list({
+      status: "published",
+      excludeReplies: true,
+      limit: pageSize,
+      offset: 4,
+    });
+    expect(page3).toHaveLength(1);
+    expect(page3[0]?.body).toBe("Post 0");
   });
-});
 
-describe("groupByDate", () => {
-  function makeItem(dateStr: string, formatted: string): TimelineItemView {
-    return {
-      post: {
-        id: 1,
-        permalink: "/p/1",
+  it("computes total pages from count", async () => {
+    for (let i = 0; i < 5; i++) {
+      await postService.create({
         format: "note",
-        status: "published",
-        featured: true,
-        pinned: false,
-        publishedAt: `${dateStr}T12:00:00.000Z`,
-        publishedAtFormatted: formatted,
-        publishedAtTime: "12:00",
-        publishedAtRelative: "1d",
-        updatedAt: `${dateStr}T12:00:00.000Z`,
-        media: [],
-      },
-    };
-  }
-
-  it("returns empty array for empty input", () => {
-    expect(groupByDate([])).toEqual([]);
-  });
-
-  it("groups items by YYYY-MM-DD date key", () => {
-    const items = [
-      makeItem("2024-02-01", "Feb 1, 2024"),
-      makeItem("2024-02-01", "Feb 1, 2024"),
-      makeItem("2024-02-02", "Feb 2, 2024"),
-    ];
-
-    const groups = groupByDate(items);
-    expect(groups).toHaveLength(2);
-    expect(groups[0]?.dateKey).toBe("2024-02-01");
-    expect(groups[0]?.label).toBe("Feb 1, 2024");
-    expect(groups[0]?.items).toHaveLength(2);
-    expect(groups[1]?.dateKey).toBe("2024-02-02");
-    expect(groups[1]?.items).toHaveLength(1);
-  });
-
-  it("creates separate groups for non-contiguous same dates", () => {
-    const items = [
-      makeItem("2024-02-01", "Feb 1, 2024"),
-      makeItem("2024-02-02", "Feb 2, 2024"),
-      makeItem("2024-02-01", "Feb 1, 2024"),
-    ];
-
-    const groups = groupByDate(items);
-    expect(groups).toHaveLength(3);
-    expect(groups[0]?.dateKey).toBe("2024-02-01");
-    expect(groups[1]?.dateKey).toBe("2024-02-02");
-    expect(groups[2]?.dateKey).toBe("2024-02-01");
-  });
-
-  it("handles a single item", () => {
-    const items = [makeItem("2024-06-15", "Jun 15, 2024")];
-    const groups = groupByDate(items);
-    expect(groups).toHaveLength(1);
-    expect(groups[0]?.dateKey).toBe("2024-06-15");
-    expect(groups[0]?.items).toHaveLength(1);
-  });
+        body: `Post ${i}`,
+      });
+    }
 
-  it("uses the first item's formatted date as the group label", () => {
-    const items = [
-      makeItem("2024-03-10", "Mar 10, 2024"),
-      makeItem("2024-03-10", "March 10"),
-    ];
+    const pageSize = 2;
+    const totalCount = await postService.count({
+      status: "published",
+      excludeReplies: true,
+    });
 
-    const groups = groupByDate(items);
-    expect(groups).toHaveLength(1);
-    // Label comes from first item in the group
-    expect(groups[0]?.label).toBe("Mar 10, 2024");
+    expect(totalCount).toBe(5);
+    const totalPages = Math.ceil(totalCount / pageSize);
+    expect(totalPages).toBe(3);
   });
 });

package/src/lib/__tests__/timezones.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest";
+import { TIMEZONES, mapIanaToTimezone } from "../timezones.js";
+
+describe("TIMEZONES", () => {
+  it("contains expected timezone entries", () => {
+    expect(TIMEZONES.length).toBeGreaterThan(30);
+    const utc = TIMEZONES.find((tz) => tz.value === "UTC");
+    expect(utc).toBeDefined();
+    expect(utc!.offset).toBe("+00:00");
+  });
+
+  it("each entry has required fields", () => {
+    for (const tz of TIMEZONES) {
+      expect(tz.value).toBeTruthy();
+      expect(tz.label).toBeTruthy();
+      expect(tz.offset).toBeTruthy();
+      expect(tz.iana.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("has no duplicate values", () => {
+    const values = TIMEZONES.map((tz) => tz.value);
+    expect(new Set(values).size).toBe(values.length);
+  });
+});
+
+describe("mapIanaToTimezone", () => {
+  it("maps Asia/Shanghai to Beijing", () => {
+    expect(mapIanaToTimezone("Asia/Shanghai")).toBe("Beijing");
+  });
+
+  it("maps America/New_York to Eastern Time", () => {
+    expect(mapIanaToTimezone("America/New_York")).toBe(
+      "Eastern Time (US & Canada)",
+    );
+  });
+
+  it("maps Europe/London to London", () => {
+    expect(mapIanaToTimezone("Europe/London")).toBe("London");
+  });
+
+  it("maps Asia/Tokyo to Tokyo", () => {
+    expect(mapIanaToTimezone("Asia/Tokyo")).toBe("Tokyo");
+  });
+
+  it("returns UTC for unknown timezone", () => {
+    expect(mapIanaToTimezone("Unknown/Zone")).toBe("UTC");
+  });
+
+  it("returns UTC for empty string", () => {
+    expect(mapIanaToTimezone("")).toBe("UTC");
+  });
+
+  it("maps Pacific/Honolulu to Hawaii", () => {
+    expect(mapIanaToTimezone("Pacific/Honolulu")).toBe("Hawaii");
+  });
+
+  it("maps Australia/Sydney to Sydney", () => {
+    expect(mapIanaToTimezone("Australia/Sydney")).toBe("Sydney");
+  });
+});

package/src/lib/__tests__/view.test.ts

@@ -34,7 +34,7 @@ function makePost(overrides: Partial<Post> = {}): Post {
     status: "published",
     featured: 0,
     pinned: 0,
-    slug: null,
+    path: null,
     title: null,
     url: null,
     body: "Hello world",
@@ -100,19 +100,25 @@ function makeNavItem(overrides: Partial<NavItem> = {}): NavItem {
 // =============================================================================
 
 describe("toPostView", () => {
-  it("generates permalink from post id when no slug", () => {
-    const post = makePostWithMedia({ id: 123, slug: null });
+  it("generates permalink from post id when no path", () => {
+    const post = makePostWithMedia({ id: 123, path: null });
     const view = toPostView(post, EMPTY_CTX);
     expect(view.permalink).toMatch(/^\/p\/.+$/);
     expect(view.permalink.length).toBeGreaterThan(3);
   });
 
-  it("generates permalink from slug when slug is set", () => {
-    const post = makePostWithMedia({ id: 123, slug: "my-post" });
+  it("generates permalink from path when path is set", () => {
+    const post = makePostWithMedia({ id: 123, path: "my-post" });
     const view = toPostView(post, EMPTY_CTX);
     expect(view.permalink).toBe("/my-post");
   });
 
+  it("generates permalink from multi-level path", () => {
+    const post = makePostWithMedia({ id: 123, path: "2024/01/my-post" });
+    const view = toPostView(post, EMPTY_CTX);
+    expect(view.permalink).toBe("/2024/01/my-post");
+  });
+
   it("formats dates correctly", () => {
     const post = makePostWithMedia({ publishedAt: 1706745600 });
     const view = toPostView(post, EMPTY_CTX);
@@ -202,7 +208,7 @@ describe("toPostView", () => {
   it("converts null fields to undefined", () => {
     const view = toPostView(makePostWithMedia(), EMPTY_CTX);
     expect(view.title).toBeUndefined();
-    expect(view.slug).toBeUndefined();
+    expect(view.path).toBeUndefined();
     expect(view.url).toBeUndefined();
     expect(view.quoteText).toBeUndefined();
     expect(view.rating).toBeUndefined();
@@ -322,8 +328,8 @@ describe("toMediaView", () => {
   it("generates local proxy URL without public URL", () => {
     const media = makeMedia();
     const view = toMediaView(media, EMPTY_CTX);
-    expect(view.url).toBe("/media/01902a9f-1a2b-7c3d.webp");
-    expect(view.thumbnailUrl).toBe("/media/01902a9f-1a2b-7c3d.webp");
+    expect(view.url).toBe("/media/2025/01/01902a9f-1a2b-7c3d.webp");
+    expect(view.thumbnailUrl).toBe("/media/2025/01/01902a9f-1a2b-7c3d.webp");
   });
 
   it("generates CDN URL with public URL", () => {
@@ -465,7 +471,7 @@ describe("toSearchResultView", () => {
         featured: 1,
         pinned: 0,
         url: "https://example.com",
-        slug: "my-link",
+        path: "my-link",
       }),
       rank: 0.8,
     };

package/src/lib/avatar-upload.ts

@@ -0,0 +1,165 @@
+/**
+ * Client-side Avatar Upload Handler
+ *
+ * Intercepts avatar file selection to generate favicon variants
+ * before uploading. Generates:
+ * - favicon.ico (ICO containing 16x16 + 32x32 PNGs)
+ * - apple-touch-icon.png (180x180 PNG)
+ *
+ * Uses the `[data-avatar-upload]` attribute on file inputs.
+ */
+
+import { encodeIco } from "./favicon.js";
+
+/**
+ * Load an image from a File object
+ */
+function loadImage(file: File): Promise<HTMLImageElement> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => {
+      URL.revokeObjectURL(img.src);
+      resolve(img);
+    };
+    img.onerror = () => reject(new Error("Failed to load image"));
+    img.src = URL.createObjectURL(file);
+  });
+}
+
+/**
+ * Resize image to a square PNG using center crop.
+ *
+ * @param img - Source HTMLImageElement
+ * @param size - Target width and height in pixels
+ * @returns PNG Blob at the target size
+ */
+function resizeToSquarePng(img: HTMLImageElement, size: number): Promise<Blob> {
+  const canvas = document.createElement("canvas");
+  canvas.width = size;
+  canvas.height = size;
+
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Failed to get canvas context");
+
+  // Cover crop: scale to fill square, crop center
+  const scale = Math.max(size / img.width, size / img.height);
+  const sw = size / scale;
+  const sh = size / scale;
+  const sx = (img.width - sw) / 2;
+  const sy = (img.height - sh) / 2;
+
+  ctx.drawImage(img, sx, sy, sw, sh, 0, 0, size, size);
+
+  return new Promise((resolve, reject) => {
+    canvas.toBlob(
+      (blob) => {
+        if (blob) resolve(blob);
+        else reject(new Error("Failed to create PNG blob"));
+      },
+      "image/png",
+    );
+  });
+}
+
+/**
+ * Process avatar file and upload with favicon variants.
+ *
+ * @param input - The file input element with `data-avatar-upload` attribute
+ * @param file - The selected file
+ */
+async function handleAvatarUpload(
+  input: HTMLInputElement,
+  file: File,
+): Promise<void> {
+  // Find the parent form for the loading button
+  const form = input.closest("form");
+  const label = form?.querySelector("label");
+  const originalText = label?.textContent ?? "";
+
+  try {
+    // Show processing state
+    if (label)
+      label.textContent = input.dataset.textProcessing || "Processing...";
+
+    // Load the image
+    const img = await loadImage(file);
+
+    // Generate variants in parallel
+    const [png16, png32, png180] = await Promise.all([
+      resizeToSquarePng(img, 16),
+      resizeToSquarePng(img, 32),
+      resizeToSquarePng(img, 180),
+    ]);
+
+    // Encode ICO with 16x16 and 32x32
+    const [png16Buf, png32Buf] = await Promise.all([
+      png16.arrayBuffer(),
+      png32.arrayBuffer(),
+    ]);
+    const icoBlob = encodeIco([
+      { size: 16, png: png16Buf },
+      { size: 32, png: png32Buf },
+    ]);
+
+    // Show uploading state
+    if (label)
+      label.textContent = input.dataset.textUploading || "Uploading...";
+
+    // Build FormData with original + variants
+    const formData = new FormData();
+    formData.append("file", file);
+    formData.append("favicon", icoBlob, "favicon.ico");
+    formData.append("appleTouch", png180, "apple-touch-icon.png");
+
+    // Upload
+    const response = await fetch("/dash/settings/avatar", {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      throw new Error("Upload failed");
+    }
+
+    // Redirect on success
+    window.location.href = "/dash/settings?saved";
+  } catch {
+    // Restore button text on error
+    if (label) label.textContent = originalText;
+    // Show error toast
+    const errorMsg =
+      input.dataset.textError || "Upload failed. Please try again.";
+    const container = document.getElementById("toast-container");
+    if (container) {
+      const toast = document.createElement("div");
+      toast.className = "toast toast-error";
+      toast.innerHTML = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><circle cx="12" cy="12" r="10"/><path d="m15 9-6 6M9 9l6 6"/></svg><span>${errorMsg}</span>`;
+      container.appendChild(toast);
+      setTimeout(() => {
+        toast.classList.add("toast-out");
+        toast.addEventListener("animationend", () => toast.remove());
+      }, 3000);
+    }
+  }
+
+  // Reset file input so the same file can be re-selected
+  input.value = "";
+}
+
+/**
+ * Initialize avatar upload via event delegation
+ */
+function initAvatarUpload(): void {
+  document.addEventListener("change", (e) => {
+    const input = (e.target as HTMLElement).closest(
+      "[data-avatar-upload]",
+    ) as HTMLInputElement | null;
+    if (!input?.files?.[0]) return;
+
+    // Prevent default form submission (Datastar data-on:change)
+    e.stopPropagation();
+    handleAvatarUpload(input, input.files[0]);
+  });
+}
+
+initAvatarUpload();

package/src/lib/config.ts

@@ -118,3 +118,50 @@ export async function getSiteDescription(c: Context): Promise<string> {
 export async function getSiteLanguage(c: Context): Promise<string> {
   return getConfig(c, "SITE_LANGUAGE");
 }
+
+/**
+ * Get home default view with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Home default view ("latest" or "featured")
+ *
+ * @example
+ * ```typescript
+ * const view = await getHomeDefaultView(c);
+ * // Returns: (DB: HOME_DEFAULT_VIEW) ?? "latest"
+ * ```
+ */
+export async function getHomeDefaultView(c: Context): Promise<string> {
+  return getConfig(c, "HOME_DEFAULT_VIEW");
+}
+
+/**
+ * Get timezone with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Timezone string (e.g. "Beijing", "UTC")
+ */
+export async function getTimeZone(c: Context): Promise<string> {
+  return getConfig(c, "TIME_ZONE");
+}
+
+/**
+ * Get site footer markdown with fallback chain: DB > ENV > Default
+ *
+ * @param c - Hono context
+ * @returns Footer markdown string (empty string if not set)
+ */
+export async function getSiteFooter(c: Context): Promise<string> {
+  return getConfig(c, "SITE_FOOTER");
+}
+
+/**
+ * Check if search engine indexing is disabled
+ *
+ * @param c - Hono context
+ * @returns true if NOINDEX is set to "true"
+ */
+export async function isNoIndex(c: Context): Promise<boolean> {
+  const value = await getConfig(c, "NOINDEX");
+  return value === "true";
+}

package/src/lib/constants.ts

@@ -7,6 +7,7 @@
  */
 export const RESERVED_PATHS = [
   "featured",
+  "latest",
   "collections",
   "signin",
   "signout",
@@ -42,18 +43,26 @@ export function isReservedPath(path: string): boolean {
 export const DEFAULT_PAGE_SIZE = 100;
 
 /**
- * Settings keys (match environment variable naming)
+ * Settings keys - derived from CONFIG_FIELDS (Single Source of Truth)
+ *
+ * Only non-envOnly fields and internal fields are stored in DB settings.
+ * Environment-only fields (SITE_URL, AUTH_SECRET, etc.) are never in the DB.
  */
-export const SETTINGS_KEYS = {
-  ONBOARDING_STATUS: "ONBOARDING_STATUS",
-  SITE_NAME: "SITE_NAME",
-  SITE_DESCRIPTION: "SITE_DESCRIPTION",
-  SITE_LANGUAGE: "SITE_LANGUAGE",
-  THEME: "THEME",
-  PASSWORD_RESET_TOKEN: "PASSWORD_RESET_TOKEN",
-} as const;
+import { CONFIG_FIELDS, type ConfigKey } from "../types.js";
+
+type SettingsFieldKey = {
+  [K in ConfigKey]: (typeof CONFIG_FIELDS)[K] extends { envOnly: false }
+    ? K
+    : never;
+}[ConfigKey];
+
+export const SETTINGS_KEYS = Object.fromEntries(
+  Object.entries(CONFIG_FIELDS)
+    .filter(([, field]) => !field.envOnly || "internal" in field)
+    .map(([key]) => [key, key]),
+) as { [K in SettingsFieldKey]: K };
 
-export type SettingsKey = (typeof SETTINGS_KEYS)[keyof typeof SETTINGS_KEYS];
+export type SettingsKey = SettingsFieldKey;
 
 /**
  * Onboarding status values

package/src/lib/favicon.ts

@@ -0,0 +1,115 @@
+/**
+ * Favicon Utilities
+ *
+ * Sizes and ICO encoding for generated favicon variants.
+ * Favicon data is stored as base64 in the settings table (not R2)
+ * since the files are tiny and accessed on every page load.
+ */
+
+/**
+ * Favicon variant sizes (width x height in pixels)
+ */
+export const FAVICON_SIZES = {
+  ICO_16: 16,
+  ICO_32: 32,
+  APPLE_TOUCH: 180,
+} as const;
+
+/**
+ * Encode PNG images into an ICO file.
+ *
+ * ICO format (with PNG payloads):
+ * - Header: 6 bytes (reserved=0, type=1, count=N)
+ * - Directory: 16 bytes per entry (width, height, colors, reserved, planes, bpp, size, offset)
+ * - Data: raw PNG bytes for each entry
+ *
+ * @param entries - Array of { size, png } where png is an ArrayBuffer of PNG data
+ * @returns ICO file as a Blob
+ *
+ * @example
+ * ```ts
+ * const ico = encodeIco([
+ *   { size: 16, png: png16ArrayBuffer },
+ *   { size: 32, png: png32ArrayBuffer },
+ * ]);
+ * ```
+ */
+export function encodeIco(
+  entries: { size: number; png: ArrayBuffer }[],
+): Blob {
+  const headerSize = 6;
+  const dirEntrySize = 16;
+  const dirSize = entries.length * dirEntrySize;
+
+  let dataOffset = headerSize + dirSize;
+
+  // Build header + directory
+  const header = new ArrayBuffer(headerSize + dirSize);
+  const view = new DataView(header);
+
+  // ICO header
+  view.setUint16(0, 0, true); // reserved
+  view.setUint16(2, 1, true); // type = icon
+  view.setUint16(4, entries.length, true); // count
+
+  const pngBuffers: ArrayBuffer[] = [];
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i]!;
+    const offset = headerSize + i * dirEntrySize;
+
+    // Width/height: 0 means 256
+    view.setUint8(offset + 0, entry.size < 256 ? entry.size : 0);
+    view.setUint8(offset + 1, entry.size < 256 ? entry.size : 0);
+    view.setUint8(offset + 2, 0); // color count (0 for >256 colors)
+    view.setUint8(offset + 3, 0); // reserved
+    view.setUint16(offset + 4, 1, true); // color planes
+    view.setUint16(offset + 6, 32, true); // bits per pixel
+    view.setUint32(offset + 8, entry.png.byteLength, true); // image size
+    view.setUint32(offset + 12, dataOffset, true); // image offset
+
+    dataOffset += entry.png.byteLength;
+    pngBuffers.push(entry.png);
+  }
+
+  return new Blob([header, ...pngBuffers], { type: "image/x-icon" });
+}
+
+/**
+ * Convert an ArrayBuffer to a base64 string.
+ *
+ * @param buffer - The ArrayBuffer to encode
+ * @returns base64-encoded string
+ *
+ * @example
+ * ```ts
+ * const b64 = arrayBufferToBase64(await blob.arrayBuffer());
+ * ```
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let binary = "";
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]!);
+  }
+  return btoa(binary);
+}
+
+/**
+ * Convert a base64 string to a Uint8Array.
+ *
+ * @param base64 - The base64 string to decode
+ * @returns decoded Uint8Array
+ *
+ * @example
+ * ```ts
+ * const bytes = base64ToUint8Array(storedBase64);
+ * ```
+ */
+export function base64ToUint8Array(base64: string): Uint8Array {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}