@fresh-editor/fresh-editor 0.1.4

package/plugins/lib/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Fresh Editor Plugin Library
+ *
+ * Shared utilities for building LSP-related plugins with common patterns.
+ *
+ * @example
+ * ```typescript
+ * import { PanelManager, NavigationController, VirtualBufferFactory } from "./lib/index.ts";
+ * import type { Location, RGB, PanelOptions } from "./lib/index.ts";
+ * ```
+ */
+
+// Types
+export type { RGB, Location, PanelOptions, PanelState, NavigationOptions, HighlightPattern } from "./types.ts";
+
+// Panel Management
+export { PanelManager } from "./panel-manager.ts";
+
+// Navigation
+export { NavigationController } from "./navigation-controller.ts";
+
+// Buffer Creation
+export { VirtualBufferFactory } from "./virtual-buffer-factory.ts";
+export type { VirtualBufferOptions, SplitBufferOptions } from "./virtual-buffer-factory.ts";

package/plugins/lib/navigation-controller.ts

@@ -0,0 +1,214 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+import type { NavigationOptions } from "./types.ts";
+
+/**
+ * NavigationController - Generic list navigation for panel plugins
+ *
+ * Handles the common pattern of:
+ * - Maintaining selected index
+ * - Boundary checking
+ * - Status message updates
+ * - Callback on selection change
+ *
+ * @example
+ * ```typescript
+ * const nav = new NavigationController<DiagnosticItem>({
+ *   itemLabel: "Diagnostic",
+ *   onSelectionChange: (item, index) => {
+ *     updateHighlight(index);
+ *   }
+ * });
+ *
+ * // Set items when panel opens
+ * nav.setItems(diagnostics);
+ *
+ * // Navigation commands
+ * function next() { nav.next(); }
+ * function prev() { nav.prev(); }
+ * ```
+ */
+export class NavigationController<T> {
+  private items: T[] = [];
+  private currentIndex: number = 0;
+  private options: NavigationOptions<T>;
+
+  constructor(options: NavigationOptions<T> = {}) {
+    this.options = {
+      itemLabel: "Item",
+      wrap: false,
+      ...options,
+    };
+  }
+
+  /**
+   * Set the items to navigate through
+   *
+   * @param items - Array of items
+   * @param resetIndex - Whether to reset index to 0 (default true)
+   */
+  setItems(items: T[], resetIndex: boolean = true): void {
+    this.items = items;
+    if (resetIndex) {
+      this.currentIndex = 0;
+    } else {
+      // Clamp to valid range
+      this.currentIndex = Math.min(this.currentIndex, Math.max(0, items.length - 1));
+    }
+  }
+
+  /**
+   * Get all items
+   */
+  getItems(): T[] {
+    return this.items;
+  }
+
+  /**
+   * Get the current selected index
+   */
+  get selectedIndex(): number {
+    return this.currentIndex;
+  }
+
+  /**
+   * Set the selected index directly
+   */
+  set selectedIndex(index: number) {
+    if (this.items.length === 0) return;
+    this.currentIndex = Math.max(0, Math.min(index, this.items.length - 1));
+    this.notifyChange();
+  }
+
+  /**
+   * Get the currently selected item
+   */
+  get selected(): T | null {
+    if (this.items.length === 0 || this.currentIndex >= this.items.length) {
+      return null;
+    }
+    return this.items[this.currentIndex];
+  }
+
+  /**
+   * Get the total number of items
+   */
+  get count(): number {
+    return this.items.length;
+  }
+
+  /**
+   * Check if there are any items
+   */
+  get isEmpty(): boolean {
+    return this.items.length === 0;
+  }
+
+  /**
+   * Move to the next item
+   */
+  next(): void {
+    if (this.items.length === 0) return;
+
+    if (this.options.wrap) {
+      this.currentIndex = (this.currentIndex + 1) % this.items.length;
+    } else {
+      this.currentIndex = Math.min(this.currentIndex + 1, this.items.length - 1);
+    }
+    this.notifyChange();
+  }
+
+  /**
+   * Move to the previous item
+   */
+  prev(): void {
+    if (this.items.length === 0) return;
+
+    if (this.options.wrap) {
+      this.currentIndex = (this.currentIndex - 1 + this.items.length) % this.items.length;
+    } else {
+      this.currentIndex = Math.max(this.currentIndex - 1, 0);
+    }
+    this.notifyChange();
+  }
+
+  /**
+   * Move to the first item
+   */
+  first(): void {
+    if (this.items.length === 0) return;
+    this.currentIndex = 0;
+    this.notifyChange();
+  }
+
+  /**
+   * Move to the last item
+   */
+  last(): void {
+    if (this.items.length === 0) return;
+    this.currentIndex = this.items.length - 1;
+    this.notifyChange();
+  }
+
+  /**
+   * Jump to a specific index
+   *
+   * @param index - Target index
+   */
+  jumpTo(index: number): void {
+    if (this.items.length === 0) return;
+    this.currentIndex = Math.max(0, Math.min(index, this.items.length - 1));
+    this.notifyChange();
+  }
+
+  /**
+   * Update the status message with current position
+   *
+   * @param customMessage - Optional custom message (overrides default)
+   */
+  showStatus(customMessage?: string): void {
+    if (this.items.length === 0) {
+      editor.setStatus(`No ${this.options.itemLabel}s`);
+      return;
+    }
+
+    const message = customMessage ||
+      `${this.options.itemLabel} ${this.currentIndex + 1}/${this.items.length}`;
+    editor.setStatus(message);
+  }
+
+  /**
+   * Reset the controller state
+   */
+  reset(): void {
+    this.items = [];
+    this.currentIndex = 0;
+  }
+
+  /**
+   * Find and select an item matching a predicate
+   *
+   * @param predicate - Function to test items
+   * @returns true if found and selected, false otherwise
+   */
+  findAndSelect(predicate: (item: T) => boolean): boolean {
+    const index = this.items.findIndex(predicate);
+    if (index !== -1) {
+      this.currentIndex = index;
+      this.notifyChange();
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Internal: Notify about selection change
+   */
+  private notifyChange(): void {
+    this.showStatus();
+
+    if (this.options.onSelectionChange && this.selected !== null) {
+      this.options.onSelectionChange(this.selected, this.currentIndex);
+    }
+  }
+}

package/plugins/lib/panel-manager.ts

@@ -0,0 +1,218 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+import type { PanelOptions, PanelState } from "./types.ts";
+
+/**
+ * PanelManager - Manages panel lifecycle for split-view plugins
+ *
+ * Handles the common pattern of:
+ * - Opening a virtual buffer in a split
+ * - Tracking source split for navigation
+ * - Closing and restoring previous state
+ * - Updating panel content
+ *
+ * @example
+ * ```typescript
+ * const panel = new PanelManager("diagnostics", "diagnostics-list");
+ *
+ * async function open() {
+ *   await panel.open({ entries: buildEntries(), ratio: 0.3 });
+ * }
+ *
+ * function close() {
+ *   panel.close();
+ * }
+ *
+ * function update() {
+ *   panel.updateContent(buildEntries());
+ * }
+ * ```
+ */
+export class PanelManager {
+  private state: PanelState = {
+    isOpen: false,
+    bufferId: null,
+    splitId: null,
+    sourceSplitId: null,
+    sourceBufferId: null,
+  };
+
+  /**
+   * Create a new PanelManager
+   *
+   * @param panelName - Display name for the panel (e.g., "*Diagnostics*")
+   * @param modeName - Mode name for keybindings (e.g., "diagnostics-list")
+   */
+  constructor(
+    private readonly panelName: string,
+    private readonly modeName: string
+  ) {}
+
+  /**
+   * Check if the panel is currently open
+   */
+  get isOpen(): boolean {
+    return this.state.isOpen;
+  }
+
+  /**
+   * Get the panel's buffer ID (null if not open)
+   */
+  get bufferId(): number | null {
+    return this.state.bufferId;
+  }
+
+  /**
+   * Get the panel's split ID (null if not open)
+   */
+  get splitId(): number | null {
+    return this.state.splitId;
+  }
+
+  /**
+   * Get the source split ID (where user was before opening panel)
+   */
+  get sourceSplitId(): number | null {
+    return this.state.sourceSplitId;
+  }
+
+  /**
+   * Get the source buffer ID (to restore when closing)
+   */
+  get sourceBufferId(): number | null {
+    return this.state.sourceBufferId;
+  }
+
+  /**
+   * Open the panel in a new split
+   *
+   * If already open, updates the content instead.
+   *
+   * @param options - Panel configuration
+   * @returns The buffer ID of the panel
+   */
+  async open(options: PanelOptions): Promise<number> {
+    const { entries, ratio = 0.3, showLineNumbers = false, editingDisabled = true } = options;
+
+    if (this.state.isOpen && this.state.bufferId !== null) {
+      // Panel already open - just update content
+      this.updateContent(entries);
+      return this.state.bufferId;
+    }
+
+    // Save current context
+    this.state.sourceSplitId = editor.getActiveSplitId();
+    this.state.sourceBufferId = editor.getActiveBufferId();
+
+    // Create virtual buffer in split
+    const bufferId = await editor.createVirtualBufferInSplit({
+      name: this.panelName,
+      mode: this.modeName,
+      read_only: true,
+      entries,
+      ratio,
+      panel_id: this.panelName,
+      show_line_numbers: showLineNumbers,
+      editing_disabled: editingDisabled,
+    });
+
+    // Track state
+    this.state.bufferId = bufferId;
+    this.state.splitId = editor.getActiveSplitId();
+    this.state.isOpen = true;
+
+    return bufferId;
+  }
+
+  /**
+   * Close the panel and restore previous state
+   */
+  close(): void {
+    if (!this.state.isOpen) {
+      return;
+    }
+
+    // Close the split containing the panel
+    if (this.state.splitId !== null) {
+      editor.closeSplit(this.state.splitId);
+    }
+
+    // Focus back on source split
+    if (this.state.sourceSplitId !== null) {
+      editor.focusSplit(this.state.sourceSplitId);
+    }
+
+    // Reset state
+    this.reset();
+  }
+
+  /**
+   * Update the panel content without closing/reopening
+   *
+   * @param entries - New entries to display
+   */
+  updateContent(entries: TextPropertyEntry[]): void {
+    if (!this.state.isOpen || this.state.bufferId === null) {
+      return;
+    }
+
+    editor.setVirtualBufferContent(this.state.bufferId, entries);
+  }
+
+  /**
+   * Reset panel state (called internally on close)
+   */
+  reset(): void {
+    this.state = {
+      isOpen: false,
+      bufferId: null,
+      splitId: null,
+      sourceSplitId: null,
+      sourceBufferId: null,
+    };
+  }
+
+  /**
+   * Focus the source split (useful for "goto" operations)
+   */
+  focusSource(): void {
+    if (this.state.sourceSplitId !== null) {
+      editor.focusSplit(this.state.sourceSplitId);
+    }
+  }
+
+  /**
+   * Focus the panel split
+   */
+  focusPanel(): void {
+    if (this.state.splitId !== null) {
+      editor.focusSplit(this.state.splitId);
+    }
+  }
+
+  /**
+   * Open a file in the source split (for navigation operations)
+   *
+   * @param filePath - Path to the file to open
+   * @param line - Line number to jump to (1-indexed)
+   * @param column - Column number to jump to (1-indexed)
+   */
+  async openInSource(filePath: string, line: number, column: number): Promise<void> {
+    if (this.state.sourceSplitId === null) {
+      return;
+    }
+
+    // Focus source split and open file
+    editor.focusSplit(this.state.sourceSplitId);
+    await editor.openFile(filePath);
+
+    // Jump to location
+    editor.gotoLine(line);
+    if (column > 1) {
+      editor.gotoColumn(column);
+    }
+
+    // Focus back on panel
+    this.focusPanel();
+  }
+}

package/plugins/lib/types.ts

@@ -0,0 +1,72 @@
+/// <reference path="./fresh.d.ts" />
+
+/**
+ * Shared Types for Fresh Editor Plugin Library
+ *
+ * Common interfaces and types used across LSP-related plugins.
+ */
+
+/**
+ * RGB color tuple for overlays and highlighting
+ */
+export type RGB = [number, number, number];
+
+/**
+ * File location with line and column
+ */
+export interface Location {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Options for opening a panel
+ */
+export interface PanelOptions {
+  /** Text property entries to display */
+  entries: TextPropertyEntry[];
+  /** Split ratio (0.0 to 1.0), default 0.3 */
+  ratio?: number;
+  /** Whether to show line numbers, default false for panels */
+  showLineNumbers?: boolean;
+  /** Whether editing is disabled, default true for panels */
+  editingDisabled?: boolean;
+}
+
+/**
+ * State of a managed panel
+ */
+export interface PanelState {
+  isOpen: boolean;
+  bufferId: number | null;
+  splitId: number | null;
+  sourceSplitId: number | null;
+  sourceBufferId: number | null;
+}
+
+/**
+ * Options for NavigationController
+ */
+export interface NavigationOptions<T> {
+  /** Function to call when selection changes */
+  onSelectionChange?: (item: T, index: number) => void;
+  /** Label for status messages (e.g., "Diagnostic", "Reference") */
+  itemLabel?: string;
+  /** Whether to wrap around at boundaries */
+  wrap?: boolean;
+}
+
+/**
+ * Highlight pattern for syntax highlighting
+ */
+export interface HighlightPattern {
+  /** Function to test if line matches */
+  match: (line: string) => boolean;
+  /** Color to apply */
+  rgb: RGB;
+  /** Whether to underline */
+  underline?: boolean;
+  /** Prefix for overlay IDs */
+  overlayIdPrefix?: string;
+}

package/plugins/lib/virtual-buffer-factory.ts

@@ -0,0 +1,158 @@
+/// <reference path="../../types/fresh.d.ts" />
+
+/**
+ * Options for creating a virtual buffer
+ */
+export interface VirtualBufferOptions {
+  /** Display name (e.g., "*Commit Details*") */
+  name: string;
+  /** Mode name for keybindings */
+  mode: string;
+  /** Text property entries */
+  entries: TextPropertyEntry[];
+  /** Whether to show line numbers (default false) */
+  showLineNumbers?: boolean;
+  /** Whether editing is disabled (default true) */
+  editingDisabled?: boolean;
+  /** Whether buffer is read-only (default true) */
+  readOnly?: boolean;
+}
+
+/**
+ * Options for creating a virtual buffer in a new split
+ */
+export interface SplitBufferOptions extends VirtualBufferOptions {
+  /** Split ratio (default 0.3) */
+  ratio?: number;
+  /** Panel ID for idempotent operations */
+  panelId?: string;
+}
+
+/**
+ * VirtualBufferFactory - Simplified virtual buffer creation
+ *
+ * Provides convenience methods for creating virtual buffers with
+ * sensible defaults for read-only panel views.
+ *
+ * @example
+ * ```typescript
+ * // Create buffer as a tab in current split (e.g., help, manual)
+ * const bufferId = await VirtualBufferFactory.create({
+ *   name: "*Help*",
+ *   mode: "help-manual",
+ *   entries: helpEntries,
+ * });
+ *
+ * // Create buffer in existing split (e.g., commit detail view)
+ * const bufferId = await VirtualBufferFactory.createInSplit(splitId, {
+ *   name: "*Commit Details*",
+ *   mode: "git-commit-detail",
+ *   entries: detailEntries,
+ * });
+ *
+ * // Create buffer in new split
+ * const bufferId = await VirtualBufferFactory.createWithSplit({
+ *   name: "*References*",
+ *   mode: "references-list",
+ *   entries: refEntries,
+ *   ratio: 0.4,
+ * });
+ * ```
+ */
+export const VirtualBufferFactory = {
+  /**
+   * Create a virtual buffer as a new tab in the current split
+   * This is ideal for documentation, help panels, and content that should
+   * appear alongside other buffers rather than in a separate split.
+   *
+   * @param options - Buffer configuration
+   * @returns Buffer ID
+   */
+  async create(options: VirtualBufferOptions): Promise<number> {
+    const {
+      name,
+      mode,
+      entries,
+      showLineNumbers = false,
+      editingDisabled = true,
+      readOnly = true,
+    } = options;
+
+    return await editor.createVirtualBuffer({
+      name,
+      mode,
+      read_only: readOnly,
+      entries,
+      show_line_numbers: showLineNumbers,
+      editing_disabled: editingDisabled,
+    });
+  },
+
+  /**
+   * Create a virtual buffer in an existing split
+   *
+   * @param splitId - Target split ID
+   * @param options - Buffer configuration
+   * @returns Buffer ID
+   */
+  async createInSplit(splitId: number, options: VirtualBufferOptions): Promise<number> {
+    const {
+      name,
+      mode,
+      entries,
+      showLineNumbers = false,
+      editingDisabled = true,
+      readOnly = true,
+    } = options;
+
+    return await editor.createVirtualBufferInExistingSplit({
+      name,
+      mode,
+      read_only: readOnly,
+      entries,
+      split_id: splitId,
+      show_line_numbers: showLineNumbers,
+      editing_disabled: editingDisabled,
+    });
+  },
+
+  /**
+   * Create a virtual buffer in a new split
+   *
+   * @param options - Buffer and split configuration
+   * @returns Buffer ID
+   */
+  async createWithSplit(options: SplitBufferOptions): Promise<number> {
+    const {
+      name,
+      mode,
+      entries,
+      ratio = 0.3,
+      panelId,
+      showLineNumbers = false,
+      editingDisabled = true,
+      readOnly = true,
+    } = options;
+
+    return await editor.createVirtualBufferInSplit({
+      name,
+      mode,
+      read_only: readOnly,
+      entries,
+      ratio,
+      panel_id: panelId,
+      show_line_numbers: showLineNumbers,
+      editing_disabled: editingDisabled,
+    });
+  },
+
+  /**
+   * Update content of an existing virtual buffer
+   *
+   * @param bufferId - Buffer to update
+   * @param entries - New entries
+   */
+  updateContent(bufferId: number, entries: TextPropertyEntry[]): void {
+    editor.setVirtualBufferContent(bufferId, entries);
+  },
+};