@optilogic/core 1.0.0-beta.15 → 1.0.0-beta.17

package/src/components/file-view/types.ts

@@ -0,0 +1,180 @@
+import type * as React from "react";
+
+// ============ CONTENT TYPES ============
+
+/**
+ * Built-in content types that FileView can render.
+ */
+export type BuiltInContentType =
+  | "code"
+  | "markdown"
+  | "image"
+  | "pdf"
+  | "csv"
+  | "html"
+  | "plaintext"
+  | "unknown";
+
+/**
+ * Content type - either a built-in type or a custom string.
+ * The `(string & {})` pattern preserves autocomplete for built-in types
+ * while accepting arbitrary strings for custom renderers.
+ */
+export type ContentType = BuiltInContentType | (string & {});
+
+// ============ IMAGE RESOLUTION ============
+
+/**
+ * Callback to resolve image `src` values to renderable URLs.
+ * Called for non-remote, non-data-URI image sources in markdown content.
+ * Can return a blob URL, data URL, or any string that works as an `<img>` src.
+ */
+export type ResolveImageUrl = (src: string) => Promise<string> | string;
+
+// ============ RENDERER TYPES ============
+
+/**
+ * Props passed to every renderer component.
+ * All renderers receive a consistent contract regardless of content type.
+ */
+export interface FileRendererProps {
+  /** Text content of the file. Null when content is binary/URL-based. */
+  content: string | null;
+  /** URL for binary content (images, PDFs). Null for text-based content. */
+  url: string | null;
+  /** The file name, used for display and language detection. */
+  fileName: string;
+  /** The resolved content type. */
+  contentType: ContentType;
+  /** Optional className for the renderer container. */
+  className?: string;
+  /** Optional callback to resolve relative image URLs in markdown content. */
+  resolveImageUrl?: ResolveImageUrl;
+}
+
+/**
+ * A renderer component that can render file content.
+ */
+export type FileRenderer = React.ComponentType<FileRendererProps>;
+
+/**
+ * Registry mapping content types to renderer components.
+ * Users can override individual renderers by providing their own map.
+ */
+export type RendererRegistry = Partial<Record<ContentType, FileRenderer>>;
+
+// ============ STATE TYPES ============
+
+/**
+ * Error information for the FileView.
+ */
+export interface FileViewError {
+  /** Error message to display. */
+  message: string;
+  /** Optional retry callback. If provided, a retry button is shown. */
+  onRetry?: () => void;
+}
+
+// ============ COMPONENT PROPS ============
+
+/**
+ * Props for the FileView component.
+ */
+export interface FileViewProps {
+  // ============ CONTENT ============
+
+  /**
+   * Text content of the file.
+   * For text-based files (code, markdown, plaintext, csv), pass the string content.
+   * For binary files (images, PDFs), pass null and use `url` instead.
+   */
+  content: string | null;
+
+  /**
+   * URL for binary content.
+   * Used for images, PDFs, and other non-text content.
+   * Can be an object URL, data URL, or HTTP URL.
+   */
+  url?: string | null;
+
+  /**
+   * The file name including extension.
+   * Used for content type detection and display context.
+   * @example "README.md", "app.tsx", "photo.png"
+   */
+  fileName: string;
+
+  // ============ CONTENT TYPE ============
+
+  /**
+   * Explicit content type override.
+   * When provided, bypasses automatic detection from fileName.
+   */
+  contentType?: ContentType;
+
+  // ============ RENDERERS ============
+
+  /**
+   * Custom renderer overrides.
+   * Merges with (and overrides) the default renderer registry.
+   * Only the types you specify are overridden; others use defaults.
+   *
+   * @example
+   * renderers={{ code: MyCustomCodeRenderer }}
+   */
+  renderers?: RendererRegistry;
+
+  // ============ STATE ============
+
+  /** Loading state. When true, shows loading indicator. */
+  loading?: boolean;
+
+  /** Error state. When provided, shows error message with optional retry. */
+  error?: FileViewError | null;
+
+  // ============ CUSTOMIZATION ============
+
+  /** Custom loading component. Replaces the default spinner. */
+  loadingComponent?: React.ReactNode;
+
+  /** Custom empty state component. Shown when content is null/empty and not loading/error. */
+  emptyComponent?: React.ReactNode;
+
+  /**
+   * Empty state message. Used when no custom emptyComponent is provided.
+   * @default "No content to display"
+   */
+  emptyMessage?: string;
+
+  /** Custom error component. Replaces the default error display. */
+  errorComponent?: React.ComponentType<{ error: FileViewError }>;
+
+  // ============ STYLING ============
+
+  /** Additional class name for the outermost container. */
+  className?: string;
+
+  /** Additional class name passed to the active renderer. */
+  rendererClassName?: string;
+
+  // ============ IMAGE RESOLUTION ============
+
+  /**
+   * Optional callback to resolve image `src` values to renderable URLs.
+   * Used by MarkdownRenderer for relative/non-remote image paths.
+   * Remote URLs (http/https) and data URIs are passed through unchanged.
+   */
+  resolveImageUrl?: ResolveImageUrl;
+}
+
+// ============ DETECTION TYPES ============
+
+/**
+ * Content type detection result.
+ */
+export interface ContentTypeDetectionResult {
+  /** The detected content type. */
+  type: ContentType;
+  /** The file extension that was matched, if any. */
+  extension: string | null;
+}

package/src/components/file-view/utils/contentTypeDetection.ts

@@ -0,0 +1,157 @@
+import type { ContentType, ContentTypeDetectionResult } from "../types";
+
+/**
+ * Extension-to-content-type mapping.
+ */
+const EXTENSION_MAP: Record<string, ContentType> = {
+  // Code / programming languages
+  ts: "code",
+  tsx: "code",
+  js: "code",
+  jsx: "code",
+  mjs: "code",
+  cjs: "code",
+  py: "code",
+  rb: "code",
+  go: "code",
+  rs: "code",
+  java: "code",
+  c: "code",
+  cpp: "code",
+  h: "code",
+  hpp: "code",
+  cs: "code",
+  php: "code",
+  swift: "code",
+  kt: "code",
+  scala: "code",
+  r: "code",
+  sql: "code",
+  sh: "code",
+  bash: "code",
+  zsh: "code",
+  ps1: "code",
+  bat: "code",
+  lua: "code",
+  perl: "code",
+  pl: "code",
+  // Config / data (code-rendered)
+  json: "code",
+  yaml: "code",
+  yml: "code",
+  toml: "code",
+  xml: "code",
+  html: "html",
+  htm: "html",
+  css: "code",
+  scss: "code",
+  sass: "code",
+  less: "code",
+  graphql: "code",
+  gql: "code",
+  // Optimization / domain-specific
+  lp: "code",
+  dat: "code",
+  // Markdown
+  md: "markdown",
+  mdx: "markdown",
+  // Images
+  png: "image",
+  jpg: "image",
+  jpeg: "image",
+  gif: "image",
+  svg: "image",
+  webp: "image",
+  ico: "image",
+  bmp: "image",
+  // PDF
+  pdf: "pdf",
+  // CSV
+  csv: "csv",
+  tsv: "csv",
+  // Plain text
+  txt: "plaintext",
+  log: "plaintext",
+  env: "plaintext",
+};
+
+/**
+ * Special file names (without extension) that map to content types.
+ */
+const SPECIAL_FILES: Record<string, ContentType> = {
+  dockerfile: "code",
+  makefile: "code",
+  rakefile: "code",
+  gemfile: "code",
+  procfile: "code",
+};
+
+/**
+ * Extract the file extension from a file name.
+ * Handles dotfiles (e.g., ".gitignore" -> "gitignore") and
+ * compound extensions (e.g., "file.test.ts" -> "ts").
+ */
+export function getFileExtension(fileName: string): string | null {
+  if (!fileName) return null;
+
+  const baseName = fileName.split("/").pop() || fileName;
+
+  // Dotfile with no other extension (e.g., ".gitignore")
+  if (baseName.startsWith(".") && !baseName.slice(1).includes(".")) {
+    return baseName.slice(1).toLowerCase();
+  }
+
+  const lastDot = baseName.lastIndexOf(".");
+  if (lastDot === -1 || lastDot === baseName.length - 1) return null;
+
+  return baseName.slice(lastDot + 1).toLowerCase();
+}
+
+/**
+ * Detect content type from a file name.
+ *
+ * @example
+ * detectContentType("app.tsx")     // { type: "code", extension: "tsx" }
+ * detectContentType("README.md")   // { type: "markdown", extension: "md" }
+ * detectContentType("photo.png")   // { type: "image", extension: "png" }
+ * detectContentType("unknown.xyz") // { type: "unknown", extension: "xyz" }
+ */
+export function detectContentType(
+  fileName: string,
+): ContentTypeDetectionResult {
+  // Check special file names first
+  const baseName = (fileName.split("/").pop() || fileName).toLowerCase();
+  const specialType = SPECIAL_FILES[baseName];
+  if (specialType) {
+    return { type: specialType, extension: baseName };
+  }
+
+  const extension = getFileExtension(fileName);
+  if (!extension) {
+    return { type: "unknown", extension: null };
+  }
+
+  const type = EXTENSION_MAP[extension] ?? "unknown";
+  return { type, extension };
+}
+
+/**
+ * Check if a content type is text-based (uses `content` string).
+ */
+export function isTextContentType(contentType: ContentType): boolean {
+  return (
+    contentType === "code" ||
+    contentType === "markdown" ||
+    contentType === "plaintext" ||
+    contentType === "csv" ||
+    contentType === "html" ||
+    contentType === "unknown"
+  );
+}
+
+/**
+ * Check if a content type is URL-based (uses `url` string).
+ */
+export function isUrlContentType(contentType: ContentType): boolean {
+  return contentType === "image" || contentType === "pdf";
+}

package/src/components/file-view/utils/index.ts

@@ -0,0 +1,12 @@
+export {
+  detectContentType,
+  getFileExtension,
+  isTextContentType,
+  isUrlContentType,
+} from "./contentTypeDetection";
+
+export {
+  DEFAULT_RENDERERS,
+  mergeRenderers,
+  resolveRenderer,
+} from "./rendererRegistry";

package/src/components/file-view/utils/languageMapping.ts

@@ -0,0 +1,78 @@
+/**
+ * Maps file extensions to shiki language IDs.
+ *
+ * Most extensions work directly as shiki lang IDs. This map only
+ * contains edge-cases where the extension differs from the shiki ID.
+ */
+const EXTENSION_OVERRIDES: Record<string, string> = {
+  yml: "yaml",
+  htm: "html",
+  cjs: "javascript",
+  mjs: "javascript",
+  jsx: "jsx",
+  tsx: "tsx",
+  h: "c",
+  hpp: "cpp",
+  cs: "csharp",
+  rb: "ruby",
+  sh: "shellscript",
+  bash: "shellscript",
+  zsh: "shellscript",
+  ps1: "powershell",
+  bat: "bat",
+  kt: "kotlin",
+  rs: "rust",
+  gql: "graphql",
+  pl: "perl",
+  sass: "sass",
+  scss: "scss",
+  less: "less",
+  // Domain-specific / data formats without shiki support
+  lp: "text",
+  dat: "text",
+  env: "shellscript",
+};
+
+/**
+ * Special file names (without extension) mapped to shiki language IDs.
+ */
+const SPECIAL_FILE_LANGUAGES: Record<string, string> = {
+  dockerfile: "dockerfile",
+  makefile: "makefile",
+  rakefile: "ruby",
+  gemfile: "ruby",
+  procfile: "yaml",
+};
+
+/**
+ * Get the shiki language ID for a given file name.
+ *
+ * @example
+ * getLanguageFromFileName("app.tsx")       // "tsx"
+ * getLanguageFromFileName("config.yml")    // "yaml"
+ * getLanguageFromFileName("Dockerfile")    // "dockerfile"
+ * getLanguageFromFileName("unknown.xyz")   // "text"
+ */
+export function getLanguageFromFileName(fileName: string): string {
+  const baseName = (fileName.split("/").pop() || fileName).toLowerCase();
+
+  // Check special file names
+  const specialLang = SPECIAL_FILE_LANGUAGES[baseName];
+  if (specialLang) return specialLang;
+
+  // Extract extension
+  let ext: string | null = null;
+  if (baseName.startsWith(".") && !baseName.slice(1).includes(".")) {
+    ext = baseName.slice(1);
+  } else {
+    const lastDot = baseName.lastIndexOf(".");
+    if (lastDot !== -1 && lastDot !== baseName.length - 1) {
+      ext = baseName.slice(lastDot + 1);
+    }
+  }
+
+  if (!ext) return "text";
+
+  // Check overrides first, then use extension directly as shiki lang ID
+  return EXTENSION_OVERRIDES[ext] ?? ext;
+}

package/src/components/file-view/utils/rendererRegistry.ts

@@ -0,0 +1,42 @@
+import type { RendererRegistry, FileRenderer } from "../types";
+import { CodeRenderer } from "../components/CodeRenderer";
+import { MarkdownRenderer } from "../components/MarkdownRenderer";
+import { ImageRenderer } from "../components/ImageRenderer";
+import { PlainTextRenderer } from "../components/PlainTextRenderer";
+import { CsvRenderer } from "../components/CsvRenderer";
+import { HtmlRenderer } from "../components/HtmlRenderer";
+
+/**
+ * Default renderer registry.
+ * Maps built-in content types to their default renderer components.
+ */
+export const DEFAULT_RENDERERS: RendererRegistry = {
+  code: CodeRenderer,
+  markdown: MarkdownRenderer,
+  image: ImageRenderer,
+  plaintext: PlainTextRenderer,
+  csv: CsvRenderer,
+  html: HtmlRenderer,
+};
+
+/**
+ * Merge user-provided renderers with defaults.
+ * User renderers override defaults for the same content type.
+ */
+export function mergeRenderers(
+  userRenderers?: RendererRegistry,
+): RendererRegistry {
+  if (!userRenderers) return DEFAULT_RENDERERS;
+  return { ...DEFAULT_RENDERERS, ...userRenderers };
+}
+
+/**
+ * Resolve a renderer for a given content type.
+ * Falls back to PlainTextRenderer if no match found.
+ */
+export function resolveRenderer(
+  registry: RendererRegistry,
+  contentType: string,
+): FileRenderer {
+  return registry[contentType] ?? registry["plaintext"] ?? PlainTextRenderer;
+}

package/src/index.ts

@@ -321,6 +321,45 @@ export {
   type UseContextMenuResult,
 } from "./components/context-menu";
 
+// FileView - Configurable file viewer with pluggable renderers
+export {
+  // Main component
+  FileView,
+
+  // Types
+  type BuiltInContentType,
+  type ContentType,
+  type ContentTypeDetectionResult,
+  type FileRendererProps,
+  type FileRenderer,
+  type RendererRegistry,
+  type FileViewError,
+  type FileViewProps,
+  type ResolveImageUrl,
+
+  // Sub-components (for custom composition or standalone use)
+  CodeRenderer,
+  MarkdownRenderer,
+  ImageRenderer,
+  PlainTextRenderer,
+  CsvRenderer,
+  HtmlRenderer,
+
+  // Hooks
+  useContentType,
+  type UseContentTypeOptions,
+  type UseContentTypeReturn,
+
+  // Utilities
+  detectContentType,
+  getFileExtension,
+  isTextContentType,
+  isUrlContentType,
+  DEFAULT_RENDERERS,
+  mergeRenderers,
+  resolveRenderer,
+} from "./components/file-view/index";
+
 // Theme system
 export {
   // Types