@jant/core 0.3.27 → 0.3.29

package/src/lib/resolve-config.ts

@@ -0,0 +1,157 @@
+/**
+ * Unified App Configuration
+ *
+ * Resolves all configuration from environment + DB settings into a single
+ * immutable object. Created once per request in middleware, then accessed
+ * via `c.var.appConfig` everywhere else.
+ *
+ * Priority: DB > ENV > Default (for user-configurable fields)
+ *           ENV > Default (for envOnly fields)
+ */
+
+import type { Bindings } from "../types/bindings.js";
+import type { AppConfig } from "../types/config.js";
+import { CONFIG_FIELDS } from "../types/config.js";
+import { getPublicUrlForProvider, getMediaUrl } from "./image.js";
+
+/**
+ * Resolve a single config value following priority rules.
+ *
+ * @param key - CONFIG_FIELDS key
+ * @param allSettings - DB settings map
+ * @param env - Worker bindings
+ * @returns Resolved string value
+ */
+function resolve(
+  key: string,
+  allSettings: Record<string, string>,
+  env: Bindings,
+): string {
+  const field = CONFIG_FIELDS[key as keyof typeof CONFIG_FIELDS];
+  if (!field) return "";
+
+  // User-configurable: DB > ENV > Default
+  if (!field.envOnly) {
+    const dbValue = allSettings[key];
+    if (dbValue) return dbValue;
+  }
+
+  // ENV > Default
+  const envValue = env[key as keyof Bindings];
+  if (envValue && typeof envValue === "string") return envValue;
+
+  return field.defaultValue;
+}
+
+/**
+ * Resolve a fallback value (ENV > Default), skipping the database.
+ * Used for placeholder values in forms.
+ *
+ * @param key - CONFIG_FIELDS key
+ * @param env - Worker bindings
+ * @returns Fallback value
+ */
+function resolveFallback(key: string, env: Bindings): string {
+  const field = CONFIG_FIELDS[key as keyof typeof CONFIG_FIELDS];
+  if (!field) return "";
+
+  const envValue = env[key as keyof Bindings];
+  if (envValue && typeof envValue === "string") return envValue;
+
+  return field.defaultValue;
+}
+
+/**
+ * Build a complete AppConfig from environment bindings and DB settings.
+ *
+ * Pure function — no side effects, no DB access.
+ *
+ * @param env - Cloudflare Worker bindings
+ * @param allSettings - All DB settings (from `services.settings.getAll()`)
+ * @returns Fully resolved AppConfig
+ *
+ * @example
+ * ```ts
+ * const allSettings = await services.settings.getAll();
+ * const appConfig = resolveConfig(c.env, allSettings);
+ * ```
+ */
+export function resolveConfig(
+  env: Bindings,
+  allSettings: Record<string, string>,
+): AppConfig {
+  const storageDriver = env.STORAGE_DRIVER || "r2";
+  const r2PublicUrl = env.R2_PUBLIC_URL || "";
+  const s3PublicUrl = env.S3_PUBLIC_URL || "";
+  const imageTransformUrl = env.IMAGE_TRANSFORM_URL || "";
+
+  // Resolve avatar URL from storage key
+  const siteAvatar = allSettings["SITE_AVATAR"] ?? "";
+  let siteAvatarUrl = "";
+  if (siteAvatar) {
+    const publicUrl = getPublicUrlForProvider(
+      storageDriver,
+      r2PublicUrl,
+      s3PublicUrl,
+    );
+    siteAvatarUrl = getMediaUrl(siteAvatar, publicUrl);
+  }
+
+  // Description is "explicit" when set in DB or ENV (not just the default)
+  const dbDescription = allSettings["SITE_DESCRIPTION"];
+  const envDescription = env.SITE_DESCRIPTION;
+  const siteDescriptionExplicit = !!(
+    dbDescription ||
+    (typeof envDescription === "string" && envDescription)
+  );
+
+  return {
+    // Site identity (DB > ENV > Default)
+    siteName: resolve("SITE_NAME", allSettings, env),
+    siteDescription: resolve("SITE_DESCRIPTION", allSettings, env),
+    siteDescriptionExplicit,
+    siteLanguage: resolve("SITE_LANGUAGE", allSettings, env),
+    homeDefaultView: resolve("HOME_DEFAULT_VIEW", allSettings, env),
+    timeZone: resolve("TIME_ZONE", allSettings, env),
+    siteFooter: resolve("SITE_FOOTER", allSettings, env),
+    noindex: resolve("NOINDEX", allSettings, env) === "true",
+
+    // Infrastructure (ENV only)
+    siteUrl: env.SITE_URL || "",
+    authConfigured: !!env.AUTH_SECRET,
+
+    // Media (ENV only)
+    storageDriver,
+    r2PublicUrl,
+    s3PublicUrl,
+    imageTransformUrl,
+
+    // Pagination/Feed (ENV only)
+    pageSize: parseInt(env.PAGE_SIZE ?? "20", 10) || 20,
+    rssFeedLimit: parseInt(env.RSS_FEED_LIMIT ?? "50", 10) || 50,
+
+    // Demo (ENV only)
+    demoEmail: env.DEMO_EMAIL || "",
+    demoPassword: env.DEMO_PASSWORD || "",
+
+    // Theme (DB internal)
+    themeId: allSettings["THEME"] ?? "",
+    defaultThemeId:
+      env.DEFAULT_THEME || CONFIG_FIELDS.DEFAULT_THEME.defaultValue,
+    fontThemeId: allSettings["FONT_THEME"] ?? "",
+    customCSS: allSettings["CUSTOM_CSS"] ?? "",
+
+    // Site appearance (DB internal)
+    siteAvatar,
+    showHeaderAvatar: allSettings["SHOW_HEADER_AVATAR"] === "true",
+    siteAvatarUrl,
+    faviconVersion: allSettings["SITE_FAVICON_VERSION"] ?? "",
+
+    // Dashboard form placeholders (ENV > Default, without DB)
+    fallbacks: {
+      siteName: resolveFallback("SITE_NAME", env),
+      siteDescription: resolveFallback("SITE_DESCRIPTION", env),
+      defaultTheme: resolveFallback("DEFAULT_THEME", env),
+    },
+  };
+}

package/src/lib/schemas.ts

@@ -16,6 +16,7 @@ import {
   NAV_ITEM_TYPES,
   MAX_MEDIA_ATTACHMENTS,
 } from "../types.js";
+import { ValidationError } from "./errors.js";
 
 /**
  * Post format enum schema
@@ -79,16 +80,14 @@ export const CreatePostSchema = z.object({
   url: z.url().optional().or(z.literal("")),
   quoteText: z.string().optional(),
   rating: RatingSchema,
-  collectionId: z.coerce
-    .number()
-    .int()
-    .min(0)
+  collectionIds: z
+    .array(z.coerce.number().int().positive())
     .optional()
-    .or(z.literal("").transform(() => undefined))
-    .transform((v) => (v === 0 ? undefined : v)),
+    .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(),
+  mediaAlts: z.record(z.string(), z.string()).optional(),
 });
 
 /**
@@ -103,7 +102,13 @@ export const CreatePageSchema = z.object({
   slug: z
     .string()
     .min(1)
-    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/),
+    .transform(normalizeSlug)
+    .pipe(
+      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(),
@@ -137,15 +142,18 @@ export const CreateCollectionSchema = z.object({
   slug: z
     .string()
     .min(1)
-    .regex(/^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$/),
+    .transform(normalizeSlug)
+    .pipe(
+      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(),
 });
 
 /**
@@ -188,6 +196,42 @@ export const ResetPasswordSchema = z
     path: ["confirmPassword"],
   });
 
+// =============================================================================
+// Slug Normalization
+// =============================================================================
+
+/**
+ * Normalize a string into a valid slug format.
+ * Lowercases, replaces non-alphanumeric characters with dashes,
+ * collapses consecutive dashes, and trims leading/trailing dashes.
+ *
+ * @param s - Raw input string
+ * @returns Normalized slug
+ * @example
+ * ```ts
+ * normalizeSlug("My Cool Page!") // "my-cool-page"
+ * normalizeSlug("  hello  world  ") // "hello-world"
+ * ```
+ */
+export function normalizeSlug(s: string): string {
+  return s
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-{2,}/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+// =============================================================================
+// Reorder Schemas
+// =============================================================================
+
+/**
+ * Reorder request schema for simple ID-based reordering
+ */
+export const ReorderSchema = z.object({
+  ids: z.array(z.coerce.number().int().positive()),
+});
+
 // =============================================================================
 // Form Data Helpers
 // =============================================================================
@@ -208,7 +252,7 @@ export function parseFormData<T>(
 ): T {
   const value = formData.get(key);
   if (value === null) {
-    throw new Error(`Missing required field: ${key}`);
+    throw new ValidationError(`Missing required field: ${key}`);
   }
   return schema.parse(value);
 }
@@ -247,3 +291,23 @@ export function validateMediaCount(mediaIds: string[]): string | null {
   }
   return null;
 }
+
+/**
+ * Parse and validate data against a Zod schema, throwing ValidationError on failure.
+ *
+ * @param schema - Zod schema to validate against
+ * @param data - Data to validate
+ * @returns Validated data
+ * @example
+ * ```ts
+ * const body = parseValidated(CreatePageSchema, await c.req.json());
+ * ```
+ */
+export function parseValidated<T>(schema: z.ZodSchema<T>, data: unknown): T {
+  const result = schema.safeParse(data);
+  if (!result.success) {
+    const firstMessage = result.error.issues[0]?.message ?? "Validation failed";
+    throw new ValidationError(firstMessage, result.error.flatten());
+  }
+  return result.data;
+}

package/src/lib/settings-bridge.ts

@@ -0,0 +1,139 @@
+/**
+ * Settings Bridge
+ *
+ * Handles server communication for the Lit settings components.
+ * Listens for `jant:settings-save` and `jant:avatar-remove` events,
+ * POSTs to the server, and handles the response (toast, DOM updates).
+ */
+
+import type {
+  SettingsSaveDetail,
+  AvatarRemoveDetail,
+} from "../ui/components/settings-types.js";
+import type { JantSettingsGeneral } from "../ui/components/jant-settings-general.js";
+import type { JantSettingsAvatar } from "../ui/components/jant-settings-avatar.js";
+import { showToast } from "./toast.js";
+
+function updateSidebarSiteName(siteName: string) {
+  const el = document.getElementById("site-name");
+  if (el) el.textContent = siteName;
+  const titleEl = document.querySelector("title");
+  if (titleEl) titleEl.textContent = `Settings - ${siteName}`;
+}
+
+// ── Settings save handler ───────────────────────────────────────────
+
+document.addEventListener("jant:settings-save", async (e: Event) => {
+  const event = e as CustomEvent<SettingsSaveDetail>;
+  const { endpoint, data, section } = event.detail;
+
+  const generalEl = document.querySelector<JantSettingsGeneral>(
+    "jant-settings-general",
+  );
+  const avatarEl = document.querySelector<JantSettingsAvatar>(
+    "jant-settings-avatar",
+  );
+
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify(data),
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+
+    const json = await res.json();
+
+    if (json.status === "redirect") {
+      window.location.href = json.url;
+      return;
+    }
+
+    if (json.toast) {
+      showToast(json.toast);
+    }
+
+    // Update sidebar site name when general settings are saved
+    if (section === "general" && json.siteName) {
+      updateSidebarSiteName(json.siteName);
+    }
+
+    // Notify the component that save succeeded
+    if (section === "avatar-display") {
+      avatarEl?.saved();
+    } else {
+      generalEl?.sectionSaved(section);
+    }
+  } catch {
+    showToast("Failed to save. Please try again.", "error");
+
+    if (section === "avatar-display") {
+      avatarEl?.saveError();
+    } else {
+      generalEl?.sectionError(section);
+    }
+  }
+});
+
+// ── Avatar remove handler ───────────────────────────────────────────
+
+document.addEventListener("jant:avatar-remove", async (e: Event) => {
+  const event = e as CustomEvent<AvatarRemoveDetail>;
+  const { endpoint } = event.detail;
+
+  try {
+    const res = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+    });
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+
+    const json = await res.json();
+
+    if (json.status === "redirect") {
+      window.location.href = json.url;
+      return;
+    }
+  } catch {
+    showToast("Failed to remove avatar. Please try again.", "error");
+  }
+});
+
+// ── Initialize form data from server-rendered JSON ──────────────────
+
+function initSettingsData() {
+  const el = document.querySelector<JantSettingsGeneral>(
+    "jant-settings-general",
+  );
+  if (!el) return;
+
+  const dataEl = document.getElementById("settings-initial-data");
+  if (!dataEl?.textContent) return;
+
+  try {
+    const data = JSON.parse(dataEl.textContent);
+    el.initData(data);
+  } catch {
+    // Data parsing failed, form will use defaults
+  }
+}
+
+// Run after Lit components have upgraded
+if (document.readyState === "loading") {
+  document.addEventListener("DOMContentLoaded", initSettingsData);
+} else {
+  // Use microtask to let custom elements upgrade first
+  queueMicrotask(initSettingsData);
+}

package/src/lib/storage.ts

@@ -71,6 +71,40 @@ export interface S3DriverConfig {
   region: string;
 }
 
+/** Constructor for an S3 command object */
+interface S3CommandCtor<TInput> {
+  new (input: TInput): unknown;
+}
+
+/** Input for PutObject */
+interface PutObjectInput {
+  Bucket: string;
+  Key: string;
+  Body: Uint8Array;
+  ContentType?: string;
+}
+
+/** Input for GetObject / DeleteObject */
+interface ObjectKeyInput {
+  Bucket: string;
+  Key: string;
+}
+
+/** Subset of GetObjectOutput used by the S3 driver */
+interface S3GetObjectOutput {
+  Body?: { transformToWebStream(): ReadableStream };
+  ContentType?: string;
+}
+
+/** Lazy-loaded S3 client bundle */
+interface S3ClientBundle {
+  send: (command: unknown) => Promise<unknown>;
+  PutObjectCommand: S3CommandCtor<PutObjectInput>;
+  GetObjectCommand: S3CommandCtor<ObjectKeyInput>;
+  DeleteObjectCommand: S3CommandCtor<ObjectKeyInput>;
+  bucket: string;
+}
+
 /**
  * Creates an S3-compatible storage driver using the AWS SDK.
  *
@@ -82,18 +116,7 @@ export interface S3DriverConfig {
  */
 export function createS3Driver(config: S3DriverConfig): StorageDriver {
   // Lazy-load the AWS SDK to avoid bundling it when using R2
-  let clientPromise: Promise<{
-    send: (command: unknown) => Promise<unknown>;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
-    S3Client: any;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
-    PutObjectCommand: any;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
-    GetObjectCommand: any;
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Dynamic import type
-    DeleteObjectCommand: any;
-    bucket: string;
-  }> | null = null;
+  let clientPromise: Promise<S3ClientBundle> | null = null;
 
   function getClient() {
     if (!clientPromise) {
@@ -110,7 +133,6 @@ export function createS3Driver(config: S3DriverConfig): StorageDriver {
         });
         return {
           send: (cmd: unknown) => client.send(cmd as never),
-          S3Client: sdk.S3Client,
           PutObjectCommand: sdk.PutObjectCommand,
           GetObjectCommand: sdk.GetObjectCommand,
           DeleteObjectCommand: sdk.DeleteObjectCommand,
@@ -163,11 +185,10 @@ export function createS3Driver(config: S3DriverConfig): StorageDriver {
           Bucket: s3.bucket,
           Key: key,
         });
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- AWS SDK response type
-        const response = (await s3.send(command)) as any;
+        const response = (await s3.send(command)) as S3GetObjectOutput;
         if (!response.Body) return null;
         return {
-          body: response.Body.transformToWebStream() as ReadableStream,
+          body: response.Body.transformToWebStream(),
           contentType: response.ContentType ?? undefined,
         };
       } catch (err: unknown) {

package/src/lib/theme.ts

@@ -6,23 +6,21 @@
 
 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.colorThemes` if provided, otherwise the built-in list.
+ * Returns the built-in color theme list.
  *
- * @param config - The Jant configuration
  * @returns Array of available color themes
  *
  * @example
  * ```typescript
- * const themes = getAvailableThemes(c.var.config);
+ * const themes = getAvailableThemes();
  * ```
  */
-export function getAvailableThemes(config: JantConfig): ColorTheme[] {
-  return config.colorThemes ?? BUILTIN_COLOR_THEMES;
+export function getAvailableThemes(): ColorTheme[] {
+  return BUILTIN_COLOR_THEMES;
 }
 
 /**
@@ -32,7 +30,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({ cssVariables })`
+ * @param cssVariables - Extra CSS variable overrides
  * @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/timeline.ts

@@ -7,14 +7,12 @@
 
 import type { Context } from "hono";
 import type { Bindings, TimelineItemView } from "../types.js";
-import type { AppVariables } from "../app.js";
+import type { AppVariables } from "../types/app-context.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.
  */
@@ -30,7 +28,7 @@ export interface TimelineResult {
  * Fetches posts using offset-based pagination, batch-loads media, identifies
  * threads, and returns render-ready `TimelineItemView[]` with page info.
  *
- * @param c - Hono context (provides services + env)
+ * @param c - Hono context (provides services + appConfig)
  * @param options - Optional page number (1-indexed, defaults to 1)
  * @returns Assembled timeline items with pagination info
  *
@@ -44,9 +42,7 @@ export async function assembleTimeline(
   c: Context<Env>,
   options?: { page?: number },
 ): Promise<TimelineResult> {
-  const pageSize =
-    parseInt(c.env.PAGE_SIZE ?? String(DEFAULT_PAGE_SIZE), 10) ||
-    DEFAULT_PAGE_SIZE;
+  const pageSize = c.var.appConfig.pageSize;
 
   const page = Math.max(1, options?.page ?? 1);
   const offset = (page - 1) * pageSize;
@@ -73,7 +69,7 @@ export async function assembleTimeline(
   // Batch load media attachments
   const postIds = posts.map((p) => p.id);
   const rawMediaMap = await c.var.services.media.getByPostIds(postIds);
-  const mediaCtx = createMediaContext(c);
+  const mediaCtx = createMediaContext(c.var.appConfig);
   const mediaMap = buildMediaMap(
     rawMediaMap,
     mediaCtx.r2PublicUrl,