@jant/core 0.3.26 → 0.3.28

package/src/lib/toast.ts

@@ -0,0 +1,134 @@
+/**
+ * Toast Utility
+ *
+ * Shared showToast() for all client-side bridge modules.
+ * Appends a temporary notification to `#toast-container`.
+ */
+
+const TOAST_ICONS = {
+  success:
+    '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><path d="m9 11 3 3L22 4"/></svg>',
+  error:
+    '<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>',
+};
+
+/**
+ * Show a toast notification.
+ *
+ * @param message - Text to display
+ * @param type - Visual style: "success" (default) or "error"
+ *
+ * @example
+ * showToast("Saved successfully.");
+ * showToast("Something went wrong", "error");
+ */
+export function showToast(
+  message: string,
+  type: "success" | "error" = "success",
+): void {
+  if (!message) return;
+
+  const container = document.getElementById("toast-container");
+  if (!container) return;
+
+  const toast = document.createElement("div");
+  toast.className = `toast toast-${type}`;
+  toast.innerHTML = `${TOAST_ICONS[type]}<span>${message}</span>`;
+  container.appendChild(toast);
+
+  setTimeout(() => {
+    toast.classList.add("toast-out");
+    toast.addEventListener("animationend", () => toast.remove());
+  }, 3000);
+}
+
+/**
+ * Show a persistent toast that stays until explicitly dismissed.
+ *
+ * @param id - Unique identifier for updating/dismissing later
+ * @param message - Text to display
+ * @param type - Visual style: "success" (default) or "error"
+ * @returns The toast element
+ *
+ * @example
+ * showPersistentToast("upload", "Uploading...");
+ */
+export function showPersistentToast(
+  id: string,
+  message: string,
+  type: "success" | "error" = "success",
+): HTMLElement | null {
+  const container = document.getElementById("toast-container");
+  if (!container) return null;
+
+  const toast = document.createElement("div");
+  toast.className = `toast toast-${type}`;
+  toast.id = `toast-${id}`;
+  toast.innerHTML = `${TOAST_ICONS[type]}<span>${message}</span>`;
+  container.appendChild(toast);
+
+  return toast;
+}
+
+/**
+ * Update the message of an existing persistent toast.
+ *
+ * @param id - The toast identifier
+ * @param message - New message text
+ *
+ * @example
+ * updateToast("upload", "Almost done...");
+ */
+export function updateToast(id: string, message: string): void {
+  const toast = document.getElementById(`toast-${id}`);
+  if (!toast) return;
+
+  const span = toast.querySelector("span");
+  if (span) span.textContent = message;
+}
+
+/**
+ * Dismiss a persistent toast with fadeout animation.
+ *
+ * @param id - The toast identifier
+ *
+ * @example
+ * dismissToast("upload");
+ */
+export function dismissToast(id: string): void {
+  const toast = document.getElementById(`toast-${id}`);
+  if (!toast) return;
+
+  toast.classList.add("toast-out");
+  toast.addEventListener("animationend", () => toast.remove());
+}
+
+/**
+ * Replace a persistent toast with an auto-dismissing one.
+ *
+ * @param id - The toast identifier
+ * @param message - New message text
+ * @param type - Visual style: "success" (default) or "error"
+ *
+ * @example
+ * replaceWithAutoClose("upload", "Published!", "success");
+ */
+export function replaceWithAutoClose(
+  id: string,
+  message: string,
+  type: "success" | "error" = "success",
+): void {
+  const toast = document.getElementById(`toast-${id}`);
+  if (!toast) {
+    showToast(message, type);
+    return;
+  }
+
+  toast.className = `toast toast-${type}`;
+  toast.innerHTML = `${TOAST_ICONS[type]}<span>${message}</span>`;
+
+  setTimeout(() => {
+    toast.classList.add("toast-out");
+    toast.addEventListener("animationend", () => toast.remove());
+  }, 3000);
+}

package/src/lib/upload.ts

@@ -0,0 +1,71 @@
+/**
+ * Upload Utilities
+ *
+ * Shared file validation and storage key generation for upload routes.
+ */
+
+import { uuidv7 } from "uuidv7";
+
+/** MIME types allowed for upload */
+const ALLOWED_UPLOAD_TYPES = [
+  "image/jpeg",
+  "image/png",
+  "image/gif",
+  "image/webp",
+  "image/svg+xml",
+] as const;
+
+/** Maximum file size in bytes (10MB) */
+const MAX_UPLOAD_SIZE = 10 * 1024 * 1024;
+
+/**
+ * Validates an uploaded file's type and size.
+ *
+ * @param file - The uploaded File object
+ * @returns null if valid, error message string if invalid
+ * @example
+ * ```ts
+ * const error = validateUploadFile(file);
+ * if (error) return dsToast(error, "error");
+ * ```
+ */
+export function validateUploadFile(file: File): string | null {
+  if (
+    !ALLOWED_UPLOAD_TYPES.includes(
+      file.type as (typeof ALLOWED_UPLOAD_TYPES)[number],
+    )
+  ) {
+    return "File type not allowed.";
+  }
+  if (file.size > MAX_UPLOAD_SIZE) {
+    return "File too large (max 10MB).";
+  }
+  return null;
+}
+
+/**
+ * Generates a unique storage key for an uploaded file.
+ * Format: `media/YYYY/MM/uuid.ext`
+ *
+ * @param originalFilename - Original filename to extract extension from
+ * @returns Object with generated id, filename, and storageKey
+ * @example
+ * ```ts
+ * const { id, filename, storageKey } = generateStorageKey("photo.jpg");
+ * // { id: "0192...", filename: "0192....jpg", storageKey: "media/2025/01/0192....jpg" }
+ * ```
+ */
+export function generateStorageKey(originalFilename: string): {
+  id: string;
+  filename: string;
+  storageKey: string;
+} {
+  const ext = originalFilename.split(".").pop() || "bin";
+  const id = uuidv7();
+  const date = new Date();
+  const year = date.getUTCFullYear();
+  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+  const filename = `${id}.${ext}`;
+  const storageKey = `media/${year}/${month}/${filename}`;
+  return { id, filename, storageKey };
+}

package/src/lib/url.ts

@@ -2,6 +2,8 @@
  * URL Utilities
  */
 
+import { pinyin } from "pinyin-pro";
+
 /**
  * Extracts the hostname (domain) from a URL string.
  *
@@ -98,7 +100,13 @@ export function isFullUrl(str: string): boolean {
  * ```
  */
 export function slugify(text: string): string {
-  return text
+  // Replace CJK characters with their pinyin equivalents, preserving non-CJK text
+  const converted = text.replace(
+    /[\u4e00-\u9fff\u3400-\u4dbf]+/g,
+    (match) => ` ${pinyin(match, { toneType: "none", separator: " " })} `,
+  );
+
+  return converted
     .toLowerCase()
     .trim()
     .replace(/[^\w\s-]/g, "")

package/src/lib/version.ts

@@ -0,0 +1,16 @@
+/**
+ * Version and environment detection
+ *
+ * In Vite dev, `__JANT_DEV__` is replaced with `true` via Vite's `define` config.
+ * In production (wrangler/esbuild), the typeof check evaluates to false safely.
+ *
+ * `__JANT_VERSION__` is replaced by Vite's `define` during both dev and lib build.
+ */
+
+declare const __JANT_DEV__: boolean | undefined;
+declare const __JANT_VERSION__: string;
+
+export const IS_VITE_DEV =
+  typeof __JANT_DEV__ !== "undefined" && __JANT_DEV__ === true;
+
+export const CORE_VERSION = __JANT_VERSION__;

package/src/lib/view.ts

@@ -5,7 +5,6 @@
  * Theme components receive only View types -- no lib/ imports needed.
  */
 
-import type { Context } from "hono";
 import type {
   Post,
   PostWithMedia,
@@ -22,6 +21,7 @@ import type {
   Format,
   Status,
   NavItemType,
+  AppConfig,
 } from "../types.js";
 import { encode } from "./sqid.js";
 import {
@@ -38,7 +38,7 @@ import { getHtmlExcerpt } from "./excerpt.js";
 // =============================================================================
 
 /**
- * Central media config -- extracted once per request from env.
+ * Central media config -- extracted once per request from appConfig.
  */
 export interface MediaContext {
   r2PublicUrl?: string;
@@ -47,16 +47,16 @@ export interface MediaContext {
 }
 
 /**
- * Creates a MediaContext from Hono context environment variables.
+ * Creates a MediaContext from AppConfig.
  *
- * @param c - Hono context
- * @returns MediaContext with env values
+ * @param appConfig - Resolved app configuration
+ * @returns MediaContext with URL values
  */
-export function createMediaContext(c: Context): MediaContext {
+export function createMediaContext(appConfig: AppConfig): MediaContext {
   return {
-    r2PublicUrl: c.env.R2_PUBLIC_URL,
-    imageTransformUrl: c.env.IMAGE_TRANSFORM_URL,
-    s3PublicUrl: c.env.S3_PUBLIC_URL,
+    r2PublicUrl: appConfig.r2PublicUrl || undefined,
+    imageTransformUrl: appConfig.imageTransformUrl || undefined,
+    s3PublicUrl: appConfig.s3PublicUrl || undefined,
   };
 }
 
@@ -154,7 +154,6 @@ export function toPostView(post: PostWithMedia, _ctx: MediaContext): PostView {
     featured: post.featured === 1,
     pinned: post.pinned === 1,
     rating: post.rating ?? undefined,
-    collectionId: post.collectionId ?? undefined,
     publishedAt: toISOString(post.publishedAt),
     publishedAtFormatted: formatDate(post.publishedAt),
     publishedAtTime: formatTime(post.publishedAt),

package/src/middleware/__tests__/auth.test.ts

@@ -1,8 +1,9 @@
 import { describe, it, expect } from "vitest";
 import { Hono } from "hono";
 import { requireAuth, requireAuthApi } from "../auth.js";
+import { errorHandler } from "../error-handler.js";
 import type { Bindings } from "../../types.js";
-import type { AppVariables } from "../../app.js";
+import type { AppVariables } from "../../types/app-context.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
@@ -59,23 +60,12 @@ describe("requireAuth", () => {
     expect(res.status).toBe(302);
     expect(res.headers.get("Location")).toBe("/login");
   });
-
-  it("redirects when auth is not configured", async () => {
-    const app = new Hono<Env>();
-    app.use("*", async (c, next) => {
-      // auth not set (undefined)
-      await next();
-    });
-    app.get("/dash", requireAuth(), (c) => c.text("Dashboard"));
-
-    const res = await app.request("/dash", { redirect: "manual" });
-    expect(res.status).toBe(302);
-  });
 });
 
 describe("requireAuthApi", () => {
   it("allows authenticated requests", async () => {
     const app = new Hono<Env>();
+    app.onError(errorHandler);
     app.use("*", async (c, next) => {
       c.set("auth", createMockAuth(true));
       await next();
@@ -91,6 +81,7 @@ describe("requireAuthApi", () => {
 
   it("returns 401 for unauthenticated requests", async () => {
     const app = new Hono<Env>();
+    app.onError(errorHandler);
     app.use("*", async (c, next) => {
       c.set("auth", createMockAuth(false));
       await next();
@@ -102,25 +93,12 @@ describe("requireAuthApi", () => {
 
     const body = await res.json();
     expect(body.error).toBe("Unauthorized");
-  });
-
-  it("returns 500 when auth is not configured", async () => {
-    const app = new Hono<Env>();
-    app.use("*", async (c, next) => {
-      // auth not set (undefined)
-      await next();
-    });
-    app.get("/api/data", requireAuthApi(), (c) => c.json({ data: "secret" }));
-
-    const res = await app.request("/api/data");
-    expect(res.status).toBe(500);
-
-    const body = await res.json();
-    expect(body.error).toBe("Authentication not configured");
+    expect(body.code).toBe("UNAUTHORIZED");
   });
 
   it("returns 401 when getSession throws", async () => {
     const app = new Hono<Env>();
+    app.onError(errorHandler);
     app.use("*", async (c, next) => {
       c.set("auth", {
         api: {

package/src/middleware/__tests__/onboarding.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach } from "vitest";
 import { Hono } from "hono";
 import { requireOnboarding, resetOnboardingCache } from "../onboarding.js";
 import type { Bindings } from "../../types.js";
-import type { AppVariables } from "../../app.js";
+import type { AppVariables } from "../../types/app-context.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 

package/src/middleware/auth.ts

@@ -6,7 +6,8 @@
 
 import type { MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
-import type { AppVariables } from "../app.js";
+import type { AppVariables } from "../types/app-context.js";
+import { DomainError, UnauthorizedError } from "../lib/errors.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 
@@ -16,10 +17,6 @@ type Env = { Bindings: Bindings; Variables: AppVariables };
  */
 export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
   return async (c, next) => {
-    if (!c.var.auth) {
-      return c.redirect(redirectTo);
-    }
-
     try {
       const session = await c.var.auth.api.getSession({
         headers: c.req.raw.headers,
@@ -42,22 +39,19 @@ export function requireAuth(redirectTo = "/signin"): MiddlewareHandler<Env> {
  */
 export function requireAuthApi(): MiddlewareHandler<Env> {
   return async (c, next) => {
-    if (!c.var.auth) {
-      return c.json({ error: "Authentication not configured" }, 500);
-    }
-
     try {
       const session = await c.var.auth.api.getSession({
         headers: c.req.raw.headers,
       });
 
       if (!session?.user) {
-        return c.json({ error: "Unauthorized" }, 401);
+        throw new UnauthorizedError();
       }
 
       await next();
-    } catch {
-      return c.json({ error: "Unauthorized" }, 401);
+    } catch (err) {
+      if (err instanceof DomainError) throw err;
+      throw new UnauthorizedError();
     }
   };
 }

package/src/middleware/config.ts

@@ -0,0 +1,51 @@
+/**
+ * Config Middleware
+ *
+ * Loads settings from DB, resolves app config and theme.
+ * Apply only to route groups that need config/theme data —
+ * skip for /health, /media/*, /favicon.ico, /api/auth/*, etc.
+ */
+
+import type { MiddlewareHandler } from "hono";
+import type { Bindings } from "../types.js";
+import type { AppVariables } from "../types/app-context.js";
+import { resolveConfig } from "../lib/resolve-config.js";
+import { buildThemeStyle } from "../lib/theme.js";
+import { BUILTIN_COLOR_THEMES } from "../ui/color-themes.js";
+import { BUILTIN_FONT_THEMES } from "../ui/font-themes.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+/**
+ * Middleware that loads settings, resolves app config, and builds theme CSS.
+ *
+ * Sets `allSettings`, `appConfig`, and `themeStyle` on the Hono context.
+ */
+export function withConfig(): MiddlewareHandler<Env> {
+  return async (c, next) => {
+    const allSettings = await c.var.services.settings.getAll();
+    c.set("allSettings", allSettings);
+    const appConfig = resolveConfig(c.env, allSettings);
+    c.set("appConfig", appConfig);
+
+    // Resolve active color theme
+    const activeTheme = BUILTIN_COLOR_THEMES.find(
+      (t) => t.id === (appConfig.themeId || appConfig.defaultThemeId),
+    );
+
+    // Build font override CSS variables
+    const fontTheme = appConfig.fontThemeId
+      ? BUILTIN_FONT_THEMES.find((f) => f.id === appConfig.fontThemeId)
+      : undefined;
+    const fontOverrides: Record<string, string> = {};
+    if (fontTheme) {
+      fontOverrides["--font-body"] = fontTheme.bodyFontFamily;
+      fontOverrides["--font-heading"] = fontTheme.headingFontFamily;
+    }
+
+    const themeStyle = buildThemeStyle(activeTheme, fontOverrides);
+    c.set("themeStyle", themeStyle);
+
+    await next();
+  };
+}

package/src/middleware/error-handler.ts

@@ -0,0 +1,56 @@
+/**
+ * Global Error Handler
+ *
+ * Maps DomainError subclasses to HTTP responses.
+ * API routes receive JSON; page routes fall through to Hono defaults.
+ */
+
+import type { ErrorHandler } from "hono";
+import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { Bindings } from "../types.js";
+import type { AppVariables } from "../types/app-context.js";
+import { DomainError, NotFoundError, ValidationError } from "../lib/errors.js";
+import { dsToast } from "../lib/sse.js";
+
+type Env = { Bindings: Bindings; Variables: AppVariables };
+
+export const errorHandler: ErrorHandler<Env> = (err, c) => {
+  // API routes: always return JSON
+  if (c.req.path.startsWith("/api/")) {
+    if (err instanceof DomainError) {
+      const body: Record<string, unknown> = {
+        error: err.message,
+        code: err.code,
+      };
+
+      if (err instanceof ValidationError && err.details) {
+        body.details = err.details;
+      }
+
+      return c.json(body, err.statusCode as ContentfulStatusCode);
+    }
+
+    // Unknown API error
+    // eslint-disable-next-line no-console -- Server error logging is intentional
+    console.error("[Jant] Unhandled error:", err);
+    return c.json({ error: "Internal server error" }, 500);
+  }
+
+  // Datastar requests: return toast
+  if (c.req.header("datastar-request")) {
+    if (err instanceof DomainError) {
+      return dsToast(err.message, "error");
+    }
+    // eslint-disable-next-line no-console -- Server error logging is intentional
+    console.error("[Jant] Unhandled error:", err);
+    return dsToast("An unexpected error occurred", "error");
+  }
+
+  // Non-API routes: map NotFoundError to Hono's built-in 404
+  if (err instanceof NotFoundError) {
+    return c.notFound();
+  }
+
+  // Everything else: re-throw for Hono's default handling
+  throw err;
+};

package/src/middleware/onboarding.ts

@@ -9,7 +9,7 @@
 
 import type { MiddlewareHandler } from "hono";
 import type { Bindings } from "../types.js";
-import type { AppVariables } from "../app.js";
+import type { AppVariables } from "../types/app-context.js";
 
 type Env = { Bindings: Bindings; Variables: AppVariables };
 

package/src/preset.css

@@ -16,6 +16,8 @@
 @theme {
   --radius-default: 0.5rem;
   --color-success: var(--success);
+  --default-font-family: var(--font-body);
+  --default-mono-font-family: var(--font-mono);
 }
 
 :root {
@@ -67,4 +69,8 @@
   a:hover {
     text-decoration-color: currentColor;
   }
+
+  :where(h1, h2, h3, h4, h5, h6) {
+    font-family: var(--font-heading);
+  }
 }