@pfmcodes/caret 0.1.1 → 0.1.2

package/esm/languages.js

@@ -18,7 +18,9 @@ import bash from "../highlight.js/es/languages/bash.js";
 import plaintext from "../highlight.js/es/languages/plaintext.js";
 import hljs from "../highlight.js/es/core.js";
 
-export function init() {
+let registeredLanguages = [];
+
+function init() {
     // Register all languages
     hljs.registerLanguage("javascript", javascript);
     hljs.registerLanguage("xml", xml);
@@ -40,7 +42,56 @@ export function init() {
     hljs.registerLanguage("bash", bash);
     hljs.registerLanguage("shell", bash);
     hljs.registerLanguage("sh", bash);
-    hljs.registerLanguage("plaintext", plaintext)
+    hljs.registerLanguage("plaintext", plaintext);
+    registeredLanguages = [
+        "javascript",
+        "js",
+        "xml",
+        "html",
+        "svg",
+        "python",
+        "java",
+        "csharp",
+        "cpp",
+        "ruby",
+        "php",
+        "go",
+        "c",
+        "rust",
+        "kotlin",
+        "swift",
+        "typescript",
+        "json",
+        "bash",
+        "shell",
+        "sh",
+        "plaintext"
+    ]
+}
+
+function registerLanguage(name, definition) {
+    hljs.registerLanguage(name, definition);
+    if (!registeredLanguages.includes(name)) {
+        registeredLanguages.push(name);
+    }
 }
 
-export default { init, registerLanguage: hljs.registerLanguage.bind(hljs), hljs };
+const languages = {
+    init,
+    registeredLanguages,
+    registerLanguage,
+    hljs
+}
+
+export default languages;
+
+/* 
+
+registeredLannguage: added for the editor.js can check if the langauge provided already is regsitered or not
+
+
+init: just registers some languages and updates the registeredLangauges variable
+
+registerLanguage: just registers a language
+
+*/

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@pfmcodes/caret",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "The official code editor engine for lexius",
   "type": "module",
   "main": "./index.cjs",
-  "types": "./types/index.d.ts",
+  "types": "./types/types.d.ts",
   "exports": {
     ".": {
       "import": "./esm/index.js",

package/types/editor.d.ts

@@ -1,27 +1,167 @@
-export interface EditorInitData {
-  /** Initial code value */
+/**
+ * Caret Editor - TypeScript Type Definitions
+ * A lightweight code editor with syntax highlighting and custom caret rendering
+ */
+
+/**
+ * Configuration options for creating a Caret editor instance
+ */
+export interface CaretEditorConfig {
+  /**
+   * Initial code content to display in the editor
+   * @default ""
+   */
   value?: string;
 
-  /** Language id registered in Highlight.js */
+  /**
+   * Programming language for syntax highlighting
+   * Must be a language supported by Highlight.js
+   * @example "javascript", "python", "html", "css"
+   */
   language: string;
 
-  /** Highlight.js theme name (without .css) */
+  /**
+   * Highlight.js theme name for syntax highlighting
+   * Can be any theme available in the highlight.js/styles directory
+   * @example "hybrid", "monokai", "github", "atom-one-dark"
+   * @default "hybrid"
+   */
   theme?: string;
 }
 
-export interface CaretEditorElements {
-  textarea: HTMLTextAreaElement;
-  highlighted: HTMLPreElement;
-  caret: HTMLDivElement;
+/**
+ * Font metrics information returned by getFontMetrics
+ */
+export interface FontMetrics {
+  /**
+   * Height of the ascender (portion of characters above baseline)
+   */
+  ascent: number;
+
+  /**
+   * Height of the descender (portion of characters below baseline)
+   */
+  descent: number;
+
+  /**
+   * Total height of the font (ascent + descent)
+   */
+  height: number;
+}
+
+/**
+ * Caret editor instance returned by createEditor
+ */
+export interface CaretEditorInstance {
+  /**
+   * Get the current value/content of the editor
+   * @returns The current code content as a string
+   */
+  getValue(): string;
+
+  /**
+   * Set the value/content of the editor
+   * @param value - The new code content to set
+   */
+  setValue(value: string): void;
+
+  /**
+   * Focus the editor textarea
+   */
+  focus(): void;
+
+  /**
+   * Change the programming language for syntax highlighting
+   * @param language - The new language identifier (e.g., "javascript", "python")
+   */
+  setLanguage(language: string): void;
+
+  /**
+   * Destroy the editor instance and remove all event listeners
+   * Cleans up the DOM and prepares for garbage collection
+   */
+  destroy(): void;
 }
 
 /**
- * Creates a Caret editor inside the given container.
- *
- * @param editor DOM element that will contain the editor
- * @param data Initial editor configuration
+ * Language manager for registering and initializing Highlight.js languages
  */
-export function createEditor(
-  editor: HTMLElement,
-  data: EditorInitData
-): Promise<void>;
+export interface LanguageManager {
+  /**
+   * Initialize the language manager
+   */
+  init(): void;
+
+  /**
+   * Register a new language for syntax highlighting
+   * @param language - The language identifier to register
+   */
+  registerLanguage(language: string): void;
+
+  /**
+   * List of currently registered languages
+   */
+  registeredLanguages: string[];
+}
+
+/**
+ * Main editor object containing the createEditor function
+ */
+export interface CaretEditor {
+  /**
+   * Create a new Caret editor instance
+   * 
+   * @param container - The HTMLElement that will contain the editor
+   * @param config - Configuration options for the editor
+   * @returns A CaretEditorInstance with methods to control the editor
+   * 
+   * @example
+   * ```typescript
+   * import editor from 'caret';
+   * 
+   * const editorContainer = document.getElementById('editor');
+   * const instance = await editor.createEditor(editorContainer, {
+   *   value: 'console.log("Hello, World!");',
+   *   language: 'javascript',
+   *   theme: 'monokai'
+   * });
+   * 
+   * // Get current value
+   * const code = instance.getValue();
+   * 
+   * // Update the content
+   * instance.setValue('const x = 42;');
+   * 
+   * // Change language
+   * instance.setLanguage('typescript');
+   * 
+   * // Clean up when done
+   * instance.destroy();
+   * ```
+   */
+  createEditor(
+    container: HTMLElement,
+    config: CaretEditorConfig
+  ): Promise<CaretEditorInstance>;
+}
+
+/**
+ * Default export - the main Caret editor object
+ */
+declare const editor: CaretEditor;
+
+export default editor;
+
+/**
+ * Module augmentation for importing Highlight.js
+ */
+declare module "../highlight.js/es/core.js" {
+  import type { HLJSApi } from "highlight.js";
+  const hljs: HLJSApi;
+  export default hljs;
+}
+
+declare module "./languages.js" {
+  const languages: LanguageManager;
+  export default languages;
+}

package/types/language-utils.d.ts

@@ -0,0 +1,428 @@
+/**
+ * Caret Editor - Language Utilities
+ * Helper types and utilities for working with language registration
+ */
+
+import type { LanguageFn } from 'highlight.js';
+import type { PreRegisteredLanguage, LanguagesModule } from './languages';
+
+/**
+ * Language information object
+ */
+export interface LanguageInfo {
+  /**
+   * Primary language identifier
+   */
+  name: string;
+
+  /**
+   * Display name for the language
+   */
+  displayName: string;
+
+  /**
+   * File extensions associated with this language
+   */
+  extensions: string[];
+
+  /**
+   * Common aliases for the language
+   */
+  aliases: string[];
+
+  /**
+   * Whether this language is pre-registered
+   */
+  isPreRegistered: boolean;
+}
+
+/**
+ * Map of language information for all pre-registered languages
+ */
+export const LANGUAGE_INFO: Record<PreRegisteredLanguage, LanguageInfo> = {
+  javascript: {
+    name: 'javascript',
+    displayName: 'JavaScript',
+    extensions: ['.js', '.mjs', '.cjs'],
+    aliases: ['js'],
+    isPreRegistered: true
+  },
+  js: {
+    name: 'javascript',
+    displayName: 'JavaScript',
+    extensions: ['.js', '.mjs', '.cjs'],
+    aliases: ['javascript'],
+    isPreRegistered: true
+  },
+  typescript: {
+    name: 'typescript',
+    displayName: 'TypeScript',
+    extensions: ['.ts', '.tsx'],
+    aliases: ['ts'],
+    isPreRegistered: true
+  },
+  python: {
+    name: 'python',
+    displayName: 'Python',
+    extensions: ['.py', '.pyw'],
+    aliases: ['py'],
+    isPreRegistered: true
+  },
+  java: {
+    name: 'java',
+    displayName: 'Java',
+    extensions: ['.java'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  csharp: {
+    name: 'csharp',
+    displayName: 'C#',
+    extensions: ['.cs'],
+    aliases: ['cs', 'c#'],
+    isPreRegistered: true
+  },
+  cpp: {
+    name: 'cpp',
+    displayName: 'C++',
+    extensions: ['.cpp', '.cc', '.cxx', '.hpp', '.h'],
+    aliases: ['c++'],
+    isPreRegistered: true
+  },
+  c: {
+    name: 'c',
+    displayName: 'C',
+    extensions: ['.c', '.h'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  ruby: {
+    name: 'ruby',
+    displayName: 'Ruby',
+    extensions: ['.rb'],
+    aliases: ['rb'],
+    isPreRegistered: true
+  },
+  php: {
+    name: 'php',
+    displayName: 'PHP',
+    extensions: ['.php'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  go: {
+    name: 'go',
+    displayName: 'Go',
+    extensions: ['.go'],
+    aliases: ['golang'],
+    isPreRegistered: true
+  },
+  rust: {
+    name: 'rust',
+    displayName: 'Rust',
+    extensions: ['.rs'],
+    aliases: ['rs'],
+    isPreRegistered: true
+  },
+  kotlin: {
+    name: 'kotlin',
+    displayName: 'Kotlin',
+    extensions: ['.kt', '.kts'],
+    aliases: ['kt'],
+    isPreRegistered: true
+  },
+  swift: {
+    name: 'swift',
+    displayName: 'Swift',
+    extensions: ['.swift'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  xml: {
+    name: 'xml',
+    displayName: 'XML',
+    extensions: ['.xml'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  html: {
+    name: 'html',
+    displayName: 'HTML',
+    extensions: ['.html', '.htm'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  svg: {
+    name: 'svg',
+    displayName: 'SVG',
+    extensions: ['.svg'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  css: {
+    name: 'css',
+    displayName: 'CSS',
+    extensions: ['.css'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  json: {
+    name: 'json',
+    displayName: 'JSON',
+    extensions: ['.json'],
+    aliases: [],
+    isPreRegistered: true
+  },
+  bash: {
+    name: 'bash',
+    displayName: 'Bash',
+    extensions: ['.sh', '.bash'],
+    aliases: ['shell', 'sh'],
+    isPreRegistered: true
+  },
+  shell: {
+    name: 'shell',
+    displayName: 'Shell',
+    extensions: ['.sh'],
+    aliases: ['bash', 'sh'],
+    isPreRegistered: true
+  },
+  sh: {
+    name: 'sh',
+    displayName: 'Shell',
+    extensions: ['.sh'],
+    aliases: ['bash', 'shell'],
+    isPreRegistered: true
+  },
+  plaintext: {
+    name: 'plaintext',
+    displayName: 'Plain Text',
+    extensions: ['.txt'],
+    aliases: ['text', 'plain'],
+    isPreRegistered: true
+  }
+};
+
+/**
+ * Type guard to check if a language is pre-registered
+ */
+export function isPreRegisteredLanguage(language: string): language is PreRegisteredLanguage {
+  const preRegistered: PreRegisteredLanguage[] = [
+    'javascript', 'js', 'xml', 'html', 'svg', 'css',
+    'python', 'java', 'csharp', 'cpp', 'ruby', 'php',
+    'go', 'c', 'rust', 'kotlin', 'swift', 'typescript',
+    'json', 'bash', 'shell', 'sh', 'plaintext'
+  ];
+  return preRegistered.includes(language as PreRegisteredLanguage);
+}
+
+/**
+ * Check if a language is currently registered
+ */
+export function isLanguageRegistered(
+  languages: LanguagesModule,
+  language: string
+): boolean {
+  return languages.registeredLanguages.includes(language);
+}
+
+/**
+ * Get language information by name or alias
+ */
+export function getLanguageInfo(language: string): LanguageInfo | null {
+  // Check if it's a direct match
+  if (isPreRegisteredLanguage(language)) {
+    return LANGUAGE_INFO[language];
+  }
+
+  // Check if it's an alias
+  for (const [key, info] of Object.entries(LANGUAGE_INFO)) {
+    if (info.aliases.includes(language)) {
+      return info;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get language by file extension
+ */
+export function getLanguageByExtension(extension: string): string | null {
+  const normalizedExt = extension.startsWith('.') ? extension : `.${extension}`;
+
+  for (const [key, info] of Object.entries(LANGUAGE_INFO)) {
+    if (info.extensions.includes(normalizedExt)) {
+      return info.name;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get all available language names (primary names only)
+ */
+export function getAllLanguageNames(): string[] {
+  const uniqueNames = new Set<string>();
+  
+  for (const info of Object.values(LANGUAGE_INFO)) {
+    uniqueNames.add(info.name);
+  }
+
+  return Array.from(uniqueNames);
+}
+
+/**
+ * Language registration helper class
+ */
+export class LanguageRegistry {
+  private languages: LanguagesModule;
+
+  constructor(languagesModule: LanguagesModule) {
+    this.languages = languagesModule;
+  }
+
+  /**
+   * Register a language if it's not already registered
+   */
+  registerIfNeeded(name: string, definition: LanguageFn): boolean {
+    if (this.isRegistered(name)) {
+      return false;
+    }
+
+    this.languages.registerLanguage(name, definition);
+    return true;
+  }
+
+  /**
+   * Check if a language is registered
+   */
+  isRegistered(name: string): boolean {
+    return isLanguageRegistered(this.languages, name);
+  }
+
+  /**
+   * Get all registered languages
+   */
+  getRegistered(): string[] {
+    return [...this.languages.registeredLanguages];
+  }
+
+  /**
+   * Get language info
+   */
+  getInfo(name: string): LanguageInfo | null {
+    return getLanguageInfo(name);
+  }
+
+  /**
+   * Register multiple languages at once
+   */
+  registerBulk(definitions: Record<string, LanguageFn>): void {
+    for (const [name, definition] of Object.entries(definitions)) {
+      this.registerIfNeeded(name, definition);
+    }
+  }
+}
+
+/**
+ * Options for lazy language loading
+ */
+export interface LazyLanguageOptions {
+  /**
+   * Base path for language modules
+   * @default "../highlight.js/es/languages/"
+   */
+  basePath?: string;
+
+  /**
+   * Whether to cache loaded languages
+   * @default true
+   */
+  cache?: boolean;
+}
+
+/**
+ * Lazy language loader for dynamic imports
+ */
+export class LazyLanguageLoader {
+  private languages: LanguagesModule;
+  private basePath: string;
+  private cache: boolean;
+  private loadedLanguages: Set<string> = new Set();
+
+  constructor(
+    languagesModule: LanguagesModule,
+    options: LazyLanguageOptions = {}
+  ) {
+    this.languages = languagesModule;
+    this.basePath = options.basePath || '../highlight.js/es/languages/';
+    this.cache = options.cache !== false;
+  }
+
+  /**
+   * Load a language dynamically
+   */
+  async loadLanguage(name: string): Promise<void> {
+    // Check if already loaded (if caching is enabled)
+    if (this.cache && this.loadedLanguages.has(name)) {
+      return;
+    }
+
+    // Check if pre-registered
+    if (isLanguageRegistered(this.languages, name)) {
+      this.loadedLanguages.add(name);
+      return;
+    }
+
+    try {
+      const module = await import(
+        `${this.basePath}${name}.js`
+      );
+      
+      const definition = module.default;
+      this.languages.registerLanguage(name, definition);
+      
+      if (this.cache) {
+        this.loadedLanguages.add(name);
+      }
+    } catch (error) {
+      throw new Error(
+        `Failed to load language "${name}": ${(error as Error).message}`
+      );
+    }
+  }
+
+  /**
+   * Load multiple languages
+   */
+  async loadLanguages(names: string[]): Promise<void> {
+    await Promise.all(names.map(name => this.loadLanguage(name)));
+  }
+
+  /**
+   * Check if a language has been loaded
+   */
+  isLoaded(name: string): boolean {
+    return this.loadedLanguages.has(name);
+  }
+
+  /**
+   * Clear the cache
+   */
+  clearCache(): void {
+    this.loadedLanguages.clear();
+  }
+}
+
+/**
+ * Export utility functions
+ */
+export const LanguageUtils = {
+  isPreRegisteredLanguage,
+  isLanguageRegistered,
+  getLanguageInfo,
+  getLanguageByExtension,
+  getAllLanguageNames
+};