tulih-editor 0.1.0

package/src/types.ts

@@ -0,0 +1,278 @@
+/**
+ * Public type definitions for TulihEditor.
+ *
+ * These types describe the plugin contract, the editor options, and the
+ * runtime context (`ctx`) handed to every plugin's `init`/`destroy` hook.
+ */
+
+/* ------------------------------------------------------------------ *
+ * Feature flags
+ * ------------------------------------------------------------------ */
+
+/**
+ * Map of plugin name -> enabled. Every built-in plugin is listed for
+ * autocomplete, but any custom plugin name is accepted too.
+ */
+export interface Features {
+  block?: boolean;
+  inline?: boolean;
+  pre?: boolean;
+  inlineCode?: boolean;
+  subSuper?: boolean;
+  removeFormat?: boolean;
+  keyboardShortcuts?: boolean;
+  readOnly?: boolean;
+  linkTooltip?: boolean;
+  emojiAutocomplete?: boolean;
+  statusBar?: boolean;
+  codeBlock?: boolean;
+  mediaEmbed?: boolean;
+  dragDrop?: boolean;
+  pastePlain?: boolean;
+  findReplace?: boolean;
+  indent?: boolean;
+  list?: boolean;
+  lineHeight?: boolean;
+  fontSize?: boolean;
+  fontFamily?: boolean;
+  specialChars?: boolean;
+  colors?: boolean;
+  tableBg?: boolean;
+  align?: boolean;
+  markdown?: boolean;
+  link?: boolean;
+  image?: boolean;
+  imageProps?: boolean;
+  imageTools?: boolean;
+  iframe?: boolean;
+  table?: boolean;
+  tableTools?: boolean;
+  hr?: boolean;
+  unlink?: boolean;
+  emoji?: boolean;
+  direction?: boolean;
+  source?: boolean;
+  history?: boolean;
+  fullscreen?: boolean;
+  toolbarCollapse?: boolean;
+  autosave?: boolean;
+  autoLinkify?: boolean;
+  caseTransform?: boolean;
+  shortcutsHelp?: boolean;
+  floatingToolbar?: boolean;
+  darkMode?: boolean;
+  shortcutCustomizer?: boolean;
+  minimal?: boolean;
+  [name: string]: boolean | undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * Options
+ * ------------------------------------------------------------------ */
+
+export interface SanitizeOptions {
+  allowedTags: string[];
+  allowedAttributes: string[];
+}
+
+/** Options accepted by `TulihEditor.attach(target, options)`. */
+export interface EditorOptions {
+  /** Enable/disable individual features (plugins). */
+  features?: Features;
+  /** Hide the classic toolbar; use the floating toolbar only. */
+  minimal?: boolean;
+  /** Custom toolbar layout. Each inner array is one button group (divider between groups). */
+  toolbar?: string[][];
+  /** Editor body height. A number is treated as pixels. */
+  height?: number | string;
+  /** Custom HTML sanitization rules (merged over the defaults). */
+  sanitize?: Partial<SanitizeOptions>;
+  /** URL schemes permitted for links. Defaults to http, https, mailto, tel. */
+  allowedUrlSchemes?: string[];
+  /** URL schemes permitted for images. Defaults to http, https, data. */
+  allowedImageSchemes?: string[];
+  /** Hostnames permitted for iframe embeds. */
+  iframeAllowlist?: string[];
+  /** `sandbox` attribute applied to embedded iframes. */
+  iframeSandbox?: string;
+  /** `allow` attribute applied to embedded iframes. */
+  iframeAllow?: string;
+  /** Start the editor in read-only mode. */
+  readOnly?: boolean;
+}
+
+/** Options after merging with defaults, stored on the editor instance. */
+export interface ResolvedOptions {
+  sanitize: SanitizeOptions;
+  urlSchemes: string[];
+  imageSchemes: string[];
+  iframeAllowlist: string[];
+  iframeSandbox: string;
+  iframeAllow: string;
+  readOnly: boolean;
+}
+
+/* ------------------------------------------------------------------ *
+ * Utilities exposed on the context
+ * ------------------------------------------------------------------ */
+
+export interface EditorUtils {
+  sanitizeHTML(html: string, sanOpts?: Partial<SanitizeOptions>): string;
+  isSafeUrl(url: string, schemes: string[]): boolean;
+  isAllowedIframeUrl(url: string): boolean;
+}
+
+/* ------------------------------------------------------------------ *
+ * Image handlers
+ * ------------------------------------------------------------------ */
+
+export type UploadImageHandler = (file: File | Blob, callback: (url: string) => void) => void;
+export type BrowseImageHandler = (context: unknown, callback: (url: string) => void) => void;
+
+/* ------------------------------------------------------------------ *
+ * Plugin contract
+ * ------------------------------------------------------------------ */
+
+/** Either a static HTML string or a builder that receives the active features. */
+export type HTMLProvider = string | ((features: Features) => string);
+export type CSSProvider = string | ((features?: Features) => string);
+
+/**
+ * A TulihEditor plugin. The only required field is `name`; everything else is
+ * optional. Plugins contribute toolbar buttons, modals, CSS, and behavior.
+ */
+export interface Plugin {
+  /** Unique plugin name. Used as the feature flag key. */
+  name: string;
+  /** Sort order in the toolbar. Plugins are grouped per 10-unit range. */
+  order?: number;
+  /** Names of plugins that must initialize before this one. */
+  deps?: string[];
+  /** Toolbar markup injected into the toolbar. */
+  toolbarHTML?: HTMLProvider;
+  /** Modal markup injected after the editor body. */
+  modalHTML?: HTMLProvider;
+  /** CSS automatically injected into <head> once, on first load. */
+  css?: CSSProvider;
+  /** Called once per editor instance after the DOM is built. */
+  init?(ctx: PluginContext): void;
+  /** Called when an editor instance is destroyed. */
+  destroy?(ctx: PluginContext): void;
+}
+
+/* ------------------------------------------------------------------ *
+ * Runtime context handed to every plugin
+ * ------------------------------------------------------------------ */
+
+export interface PluginContext {
+  /** Wrapper element containing toolbar, editor body and modals. */
+  wrapper: HTMLElement;
+  /** The contenteditable editor body (`.te-editor`). */
+  editor: HTMLElement;
+  /** The toolbar element (`.te-toolbar`). */
+  toolbar: HTMLElement;
+  /** The original textarea the editor is attached to. */
+  textarea: HTMLTextAreaElement;
+  /** Resolved feature flags for this instance. */
+  features: Features;
+  /** Resolved options for this instance. */
+  options: ResolvedOptions;
+  /** Sanitization / URL helpers. */
+  utils: EditorUtils;
+  /** The global TulihEditor object. */
+  TulihEditor: TulihEditorStatic;
+  /** Save the current selection range onto the wrapper. */
+  saveSel(): void;
+  /** Restore a previously saved selection range. */
+  restoreSel(): void;
+  /** Refresh toolbar active states (bold/italic/lists/undo/redo). */
+  updateActiveStates(): void;
+  /** Set by the pastePlain plugin to toggle plain-text pasting. */
+  _pastePlain?: boolean;
+  /** Plugins may stash additional state on the context. */
+  [key: string]: unknown;
+}
+
+/* ------------------------------------------------------------------ *
+ * Public editor instance API
+ * ------------------------------------------------------------------ */
+
+export interface EditorInstance {
+  /** Wrapper element. */
+  container: HTMLElement | null;
+  /** Contenteditable editor body. */
+  editor: HTMLElement | null;
+  /** Toolbar element. */
+  toolbar: HTMLElement | null;
+  /** Original textarea. */
+  textarea: HTMLTextAreaElement;
+  /** Resolved feature flags. */
+  features: Features;
+  /** Resolved options. */
+  options: ResolvedOptions;
+  /** Sanitization / URL helpers. */
+  utils: EditorUtils;
+
+  /** Get the editor HTML content. */
+  getContent(): string;
+  /** Replace the editor content (sanitized). */
+  setContent(html: string): void;
+  /** Get the plain text content. */
+  getText(): string;
+  /** Get the current word count. */
+  getWordCount(): number;
+  /** Get the current character count. */
+  getCharCount(): number;
+  /** Toggle read-only mode. */
+  setReadOnly(readOnly: boolean): void;
+  /** Whether the editor is currently read-only. */
+  isReadOnly(): boolean;
+  /** Tear down the editor and restore the original textarea. */
+  destroy(): void;
+}
+
+/* ------------------------------------------------------------------ *
+ * Plugin manager
+ * ------------------------------------------------------------------ */
+
+export interface PluginManagerInstance {
+  register(name: string, plugin: Plugin): this;
+  unregister(name: string): void;
+  get(name: string): Plugin | null;
+  has(name: string): boolean;
+  getNames(): string[];
+  initAll(ctx: PluginContext): void;
+  destroyAll(ctx: PluginContext): void;
+  getToolbarHTML(features: Features, toolbar?: string[][]): string;
+  getModalHTML(features: Features): string;
+  injectAllCSS(): void;
+}
+
+/* ------------------------------------------------------------------ *
+ * Global TulihEditor object
+ * ------------------------------------------------------------------ */
+
+export interface TulihEditorStatic {
+  pluginManager: PluginManagerInstance;
+  instances: EditorInstance[];
+  onBrowseImage: BrowseImageHandler | null;
+  onUploadImage?: UploadImageHandler | null;
+  setBrowseImage(handler: BrowseImageHandler): void;
+  attach(target: string | Element, options?: EditorOptions): EditorInstance | undefined;
+  create(target: string | Element, options?: EditorOptions): EditorInstance | undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * Internal element augmentations (expando properties)
+ * ------------------------------------------------------------------ */
+
+export interface TeHistory {
+  undo: string[];
+  redo: string[];
+}
+
+/** Editor body element with the table-history expando used by history/table plugins. */
+export type TeEditorElement = HTMLElement & { _tableHist?: TeHistory };
+
+/** Wrapper element with the saved-selection expando. */
+export type TeWrapperElement = HTMLElement & { __savedRange?: Range | null };