statusbar-quick-actions 0.0.10

package/src/types.ts

@@ -0,0 +1,368 @@
+/**
+ * TypeScript type definitions for StatusBar Quick Actions Extension
+ */
+
+import * as vscode from "vscode";
+
+/**
+ * Button command configuration
+ */
+export interface ButtonCommand {
+  type:
+    | "npm"
+    | "yarn"
+    | "pnpm"
+    | "bun"
+    | "shell"
+    | "github"
+    | "vscode"
+    | "task"
+    | "bunx"
+    | "npx"
+    | "pnpx"
+    | "detect";
+  script?: string;
+  command?: string;
+  args?: string[];
+}
+
+/**
+ * Icon configuration
+ */
+export interface IconConfig {
+  id: string;
+  animation?: "spin" | "pulse" | null;
+  library?: "vscode" | "material";
+  variant?: "outlined" | "filled" | "rounded" | "sharp" | "two-tone";
+  size?: "small" | "medium" | "large";
+}
+
+/**
+ * Button colors
+ */
+export interface ButtonColors {
+  foreground?: string;
+  background?: string;
+}
+
+/**
+ * Execution behavior configuration
+ */
+export interface ExecutionConfig {
+  foreground?: boolean;
+  showProgress?: boolean;
+  timeout?: number;
+  notifications?: {
+    showSuccess?: boolean;
+    showError?: boolean;
+    showOutput?: boolean;
+  };
+}
+
+/**
+ * Visibility condition
+ */
+export interface VisibilityCondition {
+  type: "fileType" | "fileExists" | "gitStatus" | "workspaceFolder";
+  patterns?: string[];
+  path?: string;
+  status?: "repository" | "clean" | "dirty" | "ahead" | "behind";
+  folders?: string[];
+  invert?: boolean;
+}
+
+/**
+ * Visibility configuration
+ */
+export interface VisibilityConfig {
+  conditions: VisibilityCondition[];
+  debounceMs?: number;
+}
+
+/**
+ * History tracking configuration
+ */
+export interface HistoryConfig {
+  enabled?: boolean;
+  maxEntries?: number;
+}
+
+/**
+ * Output panel configuration
+ */
+export interface OutputPanelConfig {
+  enabled: boolean;
+  mode: "per-button" | "shared";
+  format: "raw" | "formatted" | "ansi";
+  clearOnRun: boolean;
+  showTimestamps: boolean;
+  preserveHistory: boolean;
+  maxLines: number;
+}
+
+/**
+ * Performance configuration
+ */
+export interface PerformanceConfig {
+  visibilityDebounceMs: number;
+  enableVirtualization: boolean;
+  cacheResults: boolean;
+}
+
+/**
+ * Theme color configuration
+ */
+export interface ThemeColorConfig {
+  foreground: string;
+  background: string;
+}
+
+/**
+ * Theme configuration
+ */
+export interface ThemeConfig {
+  mode: "auto" | "dark" | "light" | "highContrast";
+  dark: {
+    button: ThemeColorConfig;
+    executing: ThemeColorConfig;
+    error: ThemeColorConfig;
+  };
+  light: {
+    button: ThemeColorConfig;
+    executing: ThemeColorConfig;
+    error: ThemeColorConfig;
+  };
+  highContrast: {
+    button: ThemeColorConfig;
+    executing: ThemeColorConfig;
+    error: ThemeColorConfig;
+  };
+}
+
+/**
+ * Notification configuration
+ */
+export interface NotificationConfig {
+  showSuccess: boolean;
+  showError: boolean;
+  showProgress: boolean;
+  position: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  duration: number;
+  includeOutput: boolean;
+}
+
+/**
+ * Button state interface
+ */
+export interface ButtonState {
+  item: vscode.StatusBarItem;
+  config: StatusBarButtonConfig;
+  isExecuting: boolean;
+  lastResult?: ExecutionResult;
+  history: ExecutionResult[];
+  accessibility: {
+    role: string;
+    ariaLabel: string;
+    focusOrder: number;
+  };
+}
+
+/**
+ * StatusBar button configuration
+ */
+export interface StatusBarButtonConfig {
+  id: string;
+  text: string;
+  tooltip?: string;
+  icon?: IconConfig;
+  command: ButtonCommand;
+  enabled?: boolean;
+  alignment?: "left" | "right";
+  priority?: number;
+  colors?: ButtonColors;
+  execution?: ExecutionConfig;
+  visibility?: VisibilityConfig;
+  workingDirectory?: string;
+  environment?: Record<string, string>;
+  history?: HistoryConfig;
+  dynamicLabel?: DynamicLabelField; // Dynamic label configuration
+}
+
+/**
+ * Extension configuration
+ */
+export interface ExtensionConfig {
+  buttons: StatusBarButtonConfig[];
+  theme?: ThemeConfig;
+  notifications?: NotificationConfig;
+  history: boolean;
+  autoDetect: boolean;
+  settings?: {
+    debug?: boolean;
+    accessibility?: {
+      keyboardNavigation?: boolean;
+      highContrast?: boolean;
+    };
+    output?: OutputPanelConfig;
+    performance?: PerformanceConfig;
+    icons?: {
+      library: "vscode" | "material";
+      defaultVariant: string;
+      defaultSize: string;
+    };
+  };
+}
+
+/**
+ * Command execution result
+ */
+export interface ExecutionResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+  duration: number;
+  timestamp: Date;
+  command: string;
+}
+
+/**
+ * Command history entry
+ */
+export interface CommandHistoryEntry {
+  id: string;
+  buttonId: string;
+  result: ExecutionResult;
+  command: string;
+}
+
+/**
+ * Execution options
+ */
+export interface ExecutionOptions {
+  workingDirectory?: string;
+  environment?: Record<string, string>;
+  timeout?: number;
+  streaming?: {
+    enabled: boolean;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    onProgress?: (percent: number) => void;
+  };
+}
+
+/**
+ * Visibility context
+ */
+export interface VisibilityContext {
+  activeFile?: vscode.Uri;
+  activeFileName?: string;
+  activeFileExtension?: string;
+  workspaceFolders?: vscode.WorkspaceFolder[];
+  gitStatus?: {
+    repository: boolean;
+    clean: boolean;
+    ahead: boolean;
+    behind: boolean;
+  };
+}
+
+/**
+ * Notification types
+ */
+export type NotificationType =
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "progress";
+
+/**
+ * Progress notification data
+ */
+export interface ProgressNotification {
+  increment?: number;
+  message?: string;
+}
+
+/**
+ * Configuration validation result
+ */
+export interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/**
+ * Menu category for nested settings
+ */
+export interface MenuCategory {
+  id: string;
+  label: string;
+  icon: string;
+  description: string;
+  items: MenuCategoryItem[];
+}
+
+/**
+ * Menu category item
+ */
+export interface MenuCategoryItem {
+  id: string;
+  label: string;
+  description?: string;
+  action: () => Promise<void>;
+}
+
+/**
+ * Button event types
+ */
+export type ButtonEvent = "click" | "hover" | "focus" | "blur";
+
+/**
+ * Dynamic label field configuration
+ */
+export interface DynamicLabelField {
+  type: "time" | "url" | "env" | "git" | "custom";
+  format?: string; // For time: date-time format string
+  url?: string; // For url: URL to fetch from
+  envVar?: string; // For env: environment variable name
+  gitInfo?: "branch" | "status" | "remote"; // For git: git information type
+  customFunction?: string; // For custom: function name to evaluate
+  refreshInterval?: number; // Refresh interval in milliseconds (0 = no auto-refresh)
+  fallback?: string; // Fallback value if evaluation fails
+  template?: string; // Template string with ${placeholder} syntax
+}
+
+/**
+ * Preset configuration for button sets
+ */
+export interface PresetConfig {
+  id: string;
+  name: string;
+  description?: string;
+  buttons: StatusBarButtonConfig[];
+  theme?: ThemeConfig;
+  metadata?: {
+    created: Date;
+    modified: Date;
+    author?: string;
+    tags?: string[];
+  };
+}
+
+/**
+ * Preset application mode
+ */
+export type PresetApplicationMode = "replace" | "merge" | "append";
+
+/**
+ * Dynamic label state
+ */
+export interface DynamicLabelState {
+  fieldConfig: DynamicLabelField;
+  lastValue: string;
+  lastUpdated: Date;
+  refreshTimer?: NodeJS.Timeout;
+  error?: string;
+}

package/src/utils/debounce.ts

@@ -0,0 +1,91 @@
+/**
+ * Debounce utility for StatusBar Quick Actions
+ */
+
+/**
+ * Creates a debounced function that delays invoking func until after wait milliseconds
+ * have elapsed since the last time the debounced function was invoked
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  wait: number,
+): (...args: Parameters<T>) => void {
+  let timeout: NodeJS.Timeout | null = null;
+
+  return function executedFunction(...args: Parameters<T>) {
+    const later = () => {
+      timeout = null;
+      func(...args);
+    };
+
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+
+    timeout = setTimeout(later, wait);
+  };
+}
+
+/**
+ * Manages debounced visibility checks for buttons
+ */
+export class DebouncedVisibilityChecker {
+  private debouncedChecks: Map<string, (...args: unknown[]) => void>;
+  private defaultDelay: number;
+
+  constructor(defaultDelay: number) {
+    this.debouncedChecks = new Map();
+    this.defaultDelay = defaultDelay;
+  }
+
+  /**
+   * Get or create a debounced check function for a button
+   */
+  public getDebouncedCheck(
+    buttonId: string,
+    checkFn: () => void,
+    customDelay?: number,
+  ): () => void {
+    const key = buttonId;
+    if (!this.debouncedChecks.has(key)) {
+      const delay = customDelay ?? this.defaultDelay;
+      this.debouncedChecks.set(key, debounce(checkFn, delay));
+    }
+    return this.debouncedChecks.get(key)!;
+  }
+
+  /**
+   * Remove a debounced check function for a button
+   */
+  public removeDebouncedCheck(buttonId: string): void {
+    this.debouncedChecks.delete(buttonId);
+  }
+
+  /**
+   * Clear all debounced check functions
+   */
+  public clear(): void {
+    this.debouncedChecks.clear();
+  }
+
+  /**
+   * Dispose of all resources
+   */
+  public dispose(): void {
+    this.clear();
+  }
+
+  /**
+   * Get the number of registered debounced checks
+   */
+  public size(): number {
+    return this.debouncedChecks.size;
+  }
+
+  /**
+   * Check if a debounced check exists for a button
+   */
+  public has(buttonId: string): boolean {
+    return this.debouncedChecks.has(buttonId);
+  }
+}