@jant/core 0.3.35 → 0.3.37

package/src/lib/upload.ts

@@ -5,40 +5,289 @@
  */
 
 import { uuidv7 } from "uuidv7";
+import type { MediaKind } from "../types/constants.js";
 
-/** MIME types allowed for upload */
-const ALLOWED_UPLOAD_TYPES = [
+/** MIME types — images */
+const IMAGE_MIME_TYPES = [
   "image/jpeg",
   "image/png",
   "image/gif",
   "image/webp",
   "image/svg+xml",
+  "image/avif",
+  "image/bmp",
+  "image/x-icon",
 ] as const;
 
-/** Maximum file size in bytes (10MB) */
-const MAX_UPLOAD_SIZE = 10 * 1024 * 1024;
+/** MIME types — video */
+const VIDEO_MIME_TYPES = [
+  "video/mp4",
+  "video/webm",
+  "video/quicktime",
+  "video/x-msvideo",
+  "video/x-matroska",
+  "video/mpeg",
+  "video/3gpp",
+  "video/x-flv",
+  "video/ogg",
+] as const;
+
+/** MIME types — audio */
+const AUDIO_MIME_TYPES = [
+  "audio/mpeg",
+  "audio/ogg",
+  "audio/wav",
+  "audio/mp4",
+  "audio/x-m4a",
+  "audio/flac",
+  "audio/aac",
+  "audio/webm",
+  "audio/x-aiff",
+  "audio/opus",
+  "audio/3gpp",
+  "audio/midi",
+] as const;
+
+/** MIME types — documents (books, PDFs) */
+const DOCUMENT_MIME_TYPES = [
+  "application/pdf",
+  "application/epub+zip",
+  "application/x-mobipocket-ebook",
+  "application/vnd.amazon.ebook",
+] as const;
+
+/** MIME types — office documents */
+const OFFICE_MIME_TYPES = [
+  "application/msword",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  "application/vnd.ms-excel",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  "application/vnd.ms-powerpoint",
+  "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  "application/vnd.oasis.opendocument.text",
+  "application/vnd.oasis.opendocument.spreadsheet",
+  "application/vnd.oasis.opendocument.presentation",
+  "application/vnd.apple.pages",
+  "application/vnd.apple.numbers",
+  "application/vnd.apple.keynote",
+] as const;
+
+/** MIME types — text & structured data */
+const TEXT_MIME_TYPES = [
+  "text/plain",
+  "text/markdown",
+  "text/csv",
+  "text/x-tiptap+json",
+  "text/html",
+  "text/css",
+  "text/javascript",
+  "text/xml",
+  "text/rtf",
+  "text/tab-separated-values",
+  "text/calendar",
+  "application/json",
+  "application/xml",
+  "application/yaml",
+  "application/toml",
+] as const;
+
+/** MIME types — archives */
+const ARCHIVE_MIME_TYPES = [
+  "application/zip",
+  "application/x-tar",
+  "application/gzip",
+  "application/x-bzip2",
+  "application/x-7z-compressed",
+  "application/x-rar-compressed",
+  "application/zstd",
+] as const;
+
+/** MIME types — fonts */
+const FONT_MIME_TYPES = [
+  "font/ttf",
+  "font/otf",
+  "font/woff",
+  "font/woff2",
+] as const;
+
+/** MIME types — 3D & design */
+const THREE_D_MIME_TYPES = [
+  "model/gltf+json",
+  "model/gltf-binary",
+  "model/obj",
+  "application/x-figma",
+  "image/vnd.dxf",
+] as const;
+
+/** MIME types — data & code */
+const CODE_MIME_TYPES = [
+  "application/sql",
+  "application/wasm",
+  "application/x-ipynb+json",
+  "application/x-sh",
+  "application/x-python-code",
+] as const;
+
+/** Lookup table from MIME type to category */
+const MIME_CATEGORY_MAP = new Map<string, MediaCategory>([
+  ...IMAGE_MIME_TYPES.map((t) => [t, "image" as const] as const),
+  ...VIDEO_MIME_TYPES.map((t) => [t, "video" as const] as const),
+  ...AUDIO_MIME_TYPES.map((t) => [t, "audio" as const] as const),
+  ...DOCUMENT_MIME_TYPES.map((t) => [t, "document" as const] as const),
+  ...OFFICE_MIME_TYPES.map((t) => [t, "office" as const] as const),
+  ...TEXT_MIME_TYPES.map((t) => [t, "text" as const] as const),
+  ...ARCHIVE_MIME_TYPES.map((t) => [t, "archive" as const] as const),
+  ...FONT_MIME_TYPES.map((t) => [t, "font" as const] as const),
+  ...THREE_D_MIME_TYPES.map((t) => [t, "3d" as const] as const),
+  ...CODE_MIME_TYPES.map((t) => [t, "code" as const] as const),
+]);
+
+/**
+ * Accept string for file inputs. Accepts all file types.
+ *
+ * @example
+ * ```ts
+ * <input type="file" accept={UPLOAD_ACCEPT} />
+ * ```
+ */
+export const UPLOAD_ACCEPT = "*/*";
+
+export type MediaCategory =
+  | "image"
+  | "video"
+  | "audio"
+  | "document"
+  | "office"
+  | "text"
+  | "archive"
+  | "font"
+  | "3d"
+  | "code";
+
+/**
+ * Returns the media category for a given MIME type.
+ * Unrecognized types default to "archive".
+ *
+ * @param mimeType - The MIME type to classify
+ * @returns The media category
+ * @example
+ * ```ts
+ * getMediaCategory("video/mp4"); // "video"
+ * getMediaCategory("text/plain"); // "text"
+ * getMediaCategory("application/octet-stream"); // "archive"
+ * ```
+ */
+export function getMediaCategory(mimeType: string): MediaCategory {
+  // Exact match from known types
+  const exact = MIME_CATEGORY_MAP.get(mimeType);
+  if (exact) return exact;
+
+  // Prefix-based fallback for unknown subtypes
+  if (mimeType.startsWith("image/")) return "image";
+  if (mimeType.startsWith("video/")) return "video";
+  if (mimeType.startsWith("audio/")) return "audio";
+  if (mimeType.startsWith("font/")) return "font";
+  if (mimeType.startsWith("model/")) return "3d";
+  if (mimeType.startsWith("text/")) return "text";
+
+  // Unknown types default to archive
+  return "archive";
+}
+
+/**
+ * Maps a MIME type to one of the five media kind categories.
+ * image/video/audio/text pass through; everything else becomes "document".
+ *
+ * @param mimeType - The MIME type to classify
+ * @returns The media kind
+ * @example
+ * ```ts
+ * toMediaKind("image/jpeg"); // "image"
+ * toMediaKind("application/pdf"); // "document"
+ * toMediaKind("text/plain"); // "text"
+ * ```
+ */
+export function toMediaKind(mimeType: string): MediaKind {
+  const category = getMediaCategory(mimeType);
+  switch (category) {
+    case "image":
+    case "video":
+    case "audio":
+    case "text":
+      return category;
+    default:
+      return "document";
+  }
+}
+
+/**
+ * Returns true if the given MIME type is an image type.
+ *
+ * @param mimeType - The MIME type to check
+ * @returns Whether the MIME type is an image
+ * @example
+ * ```ts
+ * isImageMimeType("image/jpeg"); // true
+ * isImageMimeType("video/mp4"); // false
+ * ```
+ */
+export function isImageMimeType(mimeType: string): boolean {
+  return mimeType.startsWith("image/");
+}
+
+export interface ValidateUploadOptions {
+  /** When true, only image MIME types are accepted (e.g. for avatar uploads). */
+  imagesOnly?: boolean;
+  /** Max file size in MB. */
+  maxFileSizeMB: number;
+}
 
 /**
  * Validates an uploaded file's type and size.
  *
  * @param file - The uploaded File object
+ * @param options - Validation constraints
  * @returns null if valid, error message string if invalid
  * @example
  * ```ts
- * const error = validateUploadFile(file);
+ * const error = validateUploadFile(file, { maxFileSizeMB: 500 });
  * 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.";
+export function validateUploadFile(
+  file: File,
+  options: ValidateUploadOptions,
+): string | null {
+  return validateUploadFileMetadata(file.type, file.size, options);
+}
+
+/**
+ * Validates file metadata (type and size) without requiring a File object.
+ * Used by the multipart upload initiation endpoint which receives JSON metadata.
+ * All MIME types are accepted; unrecognized types are categorized as archive.
+ *
+ * @param contentType - The MIME type of the file
+ * @param size - The file size in bytes
+ * @param options - Validation constraints
+ * @returns null if valid, error message string if invalid
+ * @example
+ * ```ts
+ * const error = validateUploadFileMetadata("image/jpeg", 1024000, { maxFileSizeMB: 500 });
+ * ```
+ */
+export function validateUploadFileMetadata(
+  contentType: string,
+  size: number,
+  options: ValidateUploadOptions,
+): string | null {
+  if (options?.imagesOnly) {
+    if (!isImageMimeType(contentType)) {
+      return "File type not allowed.";
+    }
   }
-  if (file.size > MAX_UPLOAD_SIZE) {
-    return "File too large (max 10MB).";
+  const maxMB = options.maxFileSizeMB;
+  if (size > maxMB * 1024 * 1024) {
+    return `File too large (max ${maxMB}MB).`;
   }
   return null;
 }

package/src/lib/url.ts

@@ -2,7 +2,7 @@
  * URL Utilities
  */
 
-import { pinyin } from "pinyin-pro";
+import limax from "limax";
 
 /**
  * Extracts the hostname (domain) from a URL string.
@@ -79,37 +79,52 @@ export function isFullUrl(str: string): boolean {
 /**
  * Converts text to a URL-friendly slug.
  *
- * Transforms text into a lowercase, hyphen-separated slug by:
- * - Converting to lowercase
- * - Removing special characters (keeping only word characters, spaces, and hyphens)
- * - Replacing whitespace and underscores with hyphens
- * - Removing leading and trailing hyphens
- *
- * Used for generating clean URLs from titles and names.
+ * Transforms text into a lowercase, hyphen-separated slug using limax for
+ * i18n-aware transliteration (CJK → Pinyin, Japanese → Romaji, accented → ASCII).
  *
  * @param text - The text to convert to a slug
  * @returns The slugified string
  *
  * @example
  * ```ts
- * const slug = slugify("Hello World! This is a Test.");
+ * slugify("Hello World! This is a Test.");
  * // Returns: "hello-world-this-is-a-test"
  *
- * const slug = slugify("  Multiple   Spaces  ");
- * // Returns: "multiple-spaces"
+ * slugify("书评");
+ * // Returns: "shu-ping"
  * ```
  */
 export function slugify(text: string): string {
-  // 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 limax(text, { tone: false }).replace(/_/g, "-");
+}
 
-  return converted
-    .toLowerCase()
-    .trim()
-    .replace(/[^\w\s-]/g, "")
-    .replace(/[\s_-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
+const SAFE_URL_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
+
+/**
+ * Sanitizes a URL by ensuring it uses a safe protocol.
+ *
+ * Returns the URL unchanged if it uses an allowed protocol (http:, https:, mailto:)
+ * or is a relative path. Returns an empty string for dangerous protocols like
+ * `javascript:`, `data:`, or `vbscript:`.
+ *
+ * @param url - The URL string to sanitize
+ * @returns The original URL if safe, or an empty string if the protocol is disallowed
+ *
+ * @example
+ * ```ts
+ * sanitizeUrl("https://example.com");       // "https://example.com"
+ * sanitizeUrl("/about");                     // "/about"
+ * sanitizeUrl("javascript:alert(1)");        // ""
+ * sanitizeUrl("data:text/html,<h1>Hi</h1>"); // ""
+ * ```
+ */
+export function sanitizeUrl(url: string): string {
+  try {
+    const parsed = new URL(url, "https://placeholder.invalid");
+    // Relative URLs resolve against the placeholder and get https: — allow them
+    if (SAFE_URL_PROTOCOLS.has(parsed.protocol)) return url;
+    return "";
+  } catch {
+    return "";
+  }
 }