/** Platform-agnostic modifier. 'Mod' expands to Meta (macOS) or Ctrl (others). */
export type Modifier = 'Mod' | 'Ctrl' | 'Meta' | 'Alt' | 'Shift';

export interface Hotkey {
  modifiers: Modifier[];
  key: string;
}

/**
 * Definition of an action as provided by core or a plugin.
 *
 * Actions are self-contained closures over the state they manipulate.
 * They do not receive an app-wide context object; instead, each ActionSet
 * creates actions that close over the specific state/setters they need.
 *
 * TODO: Support actions that take additional input (e.g. a provider ID to
 * switch to, a file path to open). The registry should accept a supplier
 * function that provides typeahead options for the command palette, so the
 * user can pick from a list of available providers/files when invoking the
 * action.
 */
export interface ActionDefinition {
  /** Unique ID within the source namespace (e.g. 'sidebar-toggle'). */
  id: string;
  /** Human-readable name for the command palette search. */
  name: string;
  /** Short description (shown in palette details / settings). */
  description?: string;
  /** Icon identifier for toolbar rendering. */
  icon?: string;
  /** Default hotkeys (user-remappable in future settings). */
  hotkeys?: Hotkey[];
  /** Whether holding the hotkey should repeatedly trigger this command. */
  repeatable?: boolean;
  /**
   * Optional availability check. Return false to hide from palette
   * and skip execution.
   */
  checkAvailable?(): boolean;
  /** Execute the action. */
  execute(): void | Promise<void>;
}

/** Internal representation after registration (includes source tag). */
export interface RegisteredAction extends ActionDefinition {
  /** 'core' or a plugin ID. */
  source: string;
}

/**
 * A set of actions that adapts a specific component or subsystem to the
 * action registry. ActionSets are created close to the code they adapt and
 * dependency-injected into ActionProvider.
 */
export interface ActionSet {
  /** Unique source ID for this set (used as action source prefix). */
  id: string;
  /** Get all action definitions from this set. */
  getActions(): ActionDefinition[];
}