atom/src/command-registry.js

'use strict';

const { Emitter, Disposable, CompositeDisposable } = require('event-kit');
const { calculateSpecificity, validateSelector } = require('clear-cut');
const _ = require('underscore-plus');

let SequenceCount = 0;

// Public: Associates listener functions with commands in a
// context-sensitive way using CSS selectors. You can access a global instance of
// this class via `atom.commands`, and commands registered there will be
// presented in the command palette.
//
// The global command registry facilitates a style of event handling known as
// *event delegation* that was popularized by jQuery. Atom commands are expressed
// as custom DOM events that can be invoked on the currently focused element via
// a key binding or manually via the command palette. Rather than binding
// listeners for command events directly to DOM nodes, you instead register
// command event listeners globally on `atom.commands` and constrain them to
// specific kinds of elements with CSS selectors.
//
// Command names must follow the `namespace:action` pattern, where `namespace`
// will typically be the name of your package, and `action` describes the
// behavior of your command. If either part consists of multiple words, these
// must be separated by hyphens. E.g. `awesome-package:turn-it-up-to-eleven`.
// All words should be lowercased.
//
// As the event bubbles upward through the DOM, all registered event listeners
// with matching selectors are invoked in order of specificity. In the event of a
// specificity tie, the most recently registered listener is invoked first. This
// mirrors the "cascade" semantics of CSS. Event listeners are invoked in the
// context of the current DOM node, meaning `this` always points at
// `event.currentTarget`. As is normally the case with DOM events,
// `stopPropagation` and `stopImmediatePropagation` can be used to terminate the
// bubbling process and prevent invocation of additional listeners.
//
// ## Example
//
// Here is a command that inserts the current date in an editor:
//
// ```coffee
// atom.commands.add 'atom-text-editor',
//   'user:insert-date': (event) ->
//     editor = @getModel()
//     editor.insertText(new Date().toLocaleString())
// ```
module.exports = class CommandRegistry {
  constructor() {
    this.handleCommandEvent = this.handleCommandEvent.bind(this);
    this.rootNode = null;
    this.clear();
  }

  clear() {
    this.registeredCommands = {};
    this.selectorBasedListenersByCommandName = {};
    this.inlineListenersByCommandName = {};
    this.emitter = new Emitter();
  }

  attach(rootNode) {
    this.rootNode = rootNode;
    for (const command in this.selectorBasedListenersByCommandName) {
      this.commandRegistered(command);
    }

    for (const command in this.inlineListenersByCommandName) {
      this.commandRegistered(command);
    }
  }

  destroy() {
    for (const commandName in this.registeredCommands) {
      this.rootNode.removeEventListener(
        commandName,
        this.handleCommandEvent,
        true
      );
    }
  }

  // Public: Add one or more command listeners associated with a selector.
  //
  // ## Arguments: Registering One Command
  //
  // * `target` A {String} containing a CSS selector or a DOM element. If you
  //   pass a selector, the command will be globally associated with all matching
  //   elements. The `,` combinator is not currently supported. If you pass a
  //   DOM element, the command will be associated with just that element.
  // * `commandName` A {String} containing the name of a command you want to
  //   handle such as `user:insert-date`.
  // * `listener` A listener which handles the event.  Either a {Function} to
  //   call when the given command is invoked on an element matching the
  //   selector, or an {Object} with a `didDispatch` property which is such a
  //   function.
  //
  //   The function (`listener` itself if it is a function, or the `didDispatch`
  //   method if `listener` is an object) will be called with `this` referencing
  //   the matching DOM node and the following argument:
  //     * `event`: A standard DOM event instance. Call `stopPropagation` or
  //       `stopImmediatePropagation` to terminate bubbling early.
  //
  //   Additionally, `listener` may have additional properties which are returned
  //   to those who query using `atom.commands.findCommands`, as well as several
  //   meaningful metadata properties:
  //     * `displayName`: Overrides any generated `displayName` that would
  //       otherwise be generated from the event name.
  //     * `description`: Used by consumers to display detailed information about
  //       the command.
  //     * `hiddenInCommandPalette`: If `true`, this command will not appear in
  //       the bundled command palette by default, but can still be shown with.
  //       the `Command Palette: Show Hidden Commands` command. This is a good
  //       option when you need to register large numbers of commands that don't
  //       make sense to be executed from the command palette. Please use this
  //       option conservatively, as it could reduce the discoverability of your
  //       package's commands.
  //
  // ## Arguments: Registering Multiple Commands
  //
  // * `target` A {String} containing a CSS selector or a DOM element. If you
  //   pass a selector, the commands will be globally associated with all
  //   matching elements. The `,` combinator is not currently supported.
  //   If you pass a DOM element, the command will be associated with just that
  //   element.
  // * `commands` An {Object} mapping command names like `user:insert-date` to
  //   listener {Function}s.
  //
  // Returns a {Disposable} on which `.dispose()` can be called to remove the
  // added command handler(s).
  add(target, commandName, listener, throwOnInvalidSelector = true) {
    if (typeof commandName === 'object') {
      const commands = commandName;
      throwOnInvalidSelector = listener;
      const disposable = new CompositeDisposable();
      for (commandName in commands) {
        listener = commands[commandName];
        disposable.add(
          this.add(target, commandName, listener, throwOnInvalidSelector)
        );
      }
      return disposable;
    }

    if (listener == null) {
      throw new Error('Cannot register a command with a null listener.');
    }

    // type Listener = ((e: CustomEvent) => void) | {
    //   displayName?: string,
    //   description?: string,
    //   didDispatch(e: CustomEvent): void,
    // }
    if (
      typeof listener !== 'function' &&
      typeof listener.didDispatch !== 'function'
    ) {
      throw new Error(
        'Listener must be a callback function or an object with a didDispatch method.'
      );
    }

    if (typeof target === 'string') {
      if (throwOnInvalidSelector) {
        validateSelector(target);
      }
      return this.addSelectorBasedListener(target, commandName, listener);
    } else {
      return this.addInlineListener(target, commandName, listener);
    }
  }

  addSelectorBasedListener(selector, commandName, listener) {
    if (this.selectorBasedListenersByCommandName[commandName] == null) {
      this.selectorBasedListenersByCommandName[commandName] = [];
    }
    const listenersForCommand = this.selectorBasedListenersByCommandName[
      commandName
    ];
    const selectorListener = new SelectorBasedListener(
      selector,
      commandName,
      listener
    );
    listenersForCommand.push(selectorListener);

    this.commandRegistered(commandName);

    return new Disposable(() => {
      listenersForCommand.splice(
        listenersForCommand.indexOf(selectorListener),
        1
      );
      if (listenersForCommand.length === 0) {
        delete this.selectorBasedListenersByCommandName[commandName];
      }
    });
  }

  addInlineListener(element, commandName, listener) {
    if (this.inlineListenersByCommandName[commandName] == null) {
      this.inlineListenersByCommandName[commandName] = new WeakMap();
    }

    const listenersForCommand = this.inlineListenersByCommandName[commandName];
    let listenersForElement = listenersForCommand.get(element);
    if (!listenersForElement) {
      listenersForElement = [];
      listenersForCommand.set(element, listenersForElement);
    }
    const inlineListener = new InlineListener(commandName, listener);
    listenersForElement.push(inlineListener);

    this.commandRegistered(commandName);

    return new Disposable(() => {
      listenersForElement.splice(
        listenersForElement.indexOf(inlineListener),
        1
      );
      if (listenersForElement.length === 0) {
        listenersForCommand.delete(element);
      }
    });
  }

  // Public: Find all registered commands matching a query.
  //
  // * `params` An {Object} containing one or more of the following keys:
  //   * `target` A DOM node that is the hypothetical target of a given command.
  //
  // Returns an {Array} of `CommandDescriptor` {Object}s containing the following keys:
  //  * `name` The name of the command. For example, `user:insert-date`.
  //  * `displayName` The display name of the command. For example,
  //    `User: Insert Date`.
  // Additional metadata may also be present in the returned descriptor:
  //  * `description` a {String} describing the function of the command in more
  //    detail than the title
  //  * `tags` an {Array} of {String}s that describe keywords related to the
  //    command
  //  Any additional nonstandard metadata provided when the command was `add`ed
  //  may also be present in the returned descriptor.
  findCommands({ target }) {
    const commandNames = new Set();
    const commands = [];
    let currentTarget = target;
    while (true) {
      let listeners;
      for (const name in this.inlineListenersByCommandName) {
        listeners = this.inlineListenersByCommandName[name];
        if (listeners.has(currentTarget) && !commandNames.has(name)) {
          commandNames.add(name);
          const targetListeners = listeners.get(currentTarget);
          commands.push(
            ...targetListeners.map(listener => listener.descriptor)
          );
        }
      }

      for (const commandName in this.selectorBasedListenersByCommandName) {
        listeners = this.selectorBasedListenersByCommandName[commandName];
        for (const listener of listeners) {
          if (listener.matchesTarget(currentTarget)) {
            if (!commandNames.has(commandName)) {
              commandNames.add(commandName);
              commands.push(listener.descriptor);
            }
          }
        }
      }

      if (currentTarget === window) {
        break;
      }
      currentTarget = currentTarget.parentNode || window;
    }

    return commands;
  }

  // Public: Simulate the dispatch of a command on a DOM node.
  //
  // This can be useful for testing when you want to simulate the invocation of a
  // command on a detached DOM node. Otherwise, the DOM node in question needs to
  // be attached to the document so the event bubbles up to the root node to be
  // processed.
  //
  // * `target` The DOM node at which to start bubbling the command event.
  // * `commandName` {String} indicating the name of the command to dispatch.
  dispatch(target, commandName, detail) {
    const event = new CustomEvent(commandName, { bubbles: true, detail });
    Object.defineProperty(event, 'target', { value: target });
    return this.handleCommandEvent(event);
  }

  // Public: Invoke the given callback before dispatching a command event.
  //
  // * `callback` {Function} to be called before dispatching each command
  //   * `event` The Event that will be dispatched
  onWillDispatch(callback) {
    return this.emitter.on('will-dispatch', callback);
  }

  // Public: Invoke the given callback after dispatching a command event.
  //
  // * `callback` {Function} to be called after dispatching each command
  //   * `event` The Event that was dispatched
  onDidDispatch(callback) {
    return this.emitter.on('did-dispatch', callback);
  }

  getSnapshot() {
    const snapshot = {};
    for (const commandName in this.selectorBasedListenersByCommandName) {
      const listeners = this.selectorBasedListenersByCommandName[commandName];
      snapshot[commandName] = listeners.slice();
    }
    return snapshot;
  }

  restoreSnapshot(snapshot) {
    this.selectorBasedListenersByCommandName = {};
    for (const commandName in snapshot) {
      const listeners = snapshot[commandName];
      this.selectorBasedListenersByCommandName[commandName] = listeners.slice();
    }
  }

  handleCommandEvent(event) {
    let propagationStopped = false;
    let immediatePropagationStopped = false;
    let matched = [];
    let currentTarget = event.target;

    const dispatchedEvent = new CustomEvent(event.type, {
      bubbles: true,
      detail: event.detail
    });
    Object.defineProperty(dispatchedEvent, 'eventPhase', {
      value: Event.BUBBLING_PHASE
    });
    Object.defineProperty(dispatchedEvent, 'currentTarget', {
      get() {
        return currentTarget;
      }
    });
    Object.defineProperty(dispatchedEvent, 'target', { value: currentTarget });
    Object.defineProperty(dispatchedEvent, 'preventDefault', {
      value() {
        return event.preventDefault();
      }
    });
    Object.defineProperty(dispatchedEvent, 'stopPropagation', {
      value() {
        event.stopPropagation();
        propagationStopped = true;
      }
    });
    Object.defineProperty(dispatchedEvent, 'stopImmediatePropagation', {
      value() {
        event.stopImmediatePropagation();
        propagationStopped = true;
        immediatePropagationStopped = true;
      }
    });
    Object.defineProperty(dispatchedEvent, 'abortKeyBinding', {
      value() {
        if (typeof event.abortKeyBinding === 'function') {
          event.abortKeyBinding();
        }
      }
    });

    for (const key of Object.keys(event)) {
      if (!(key in dispatchedEvent)) {
        dispatchedEvent[key] = event[key];
      }
    }

    this.emitter.emit('will-dispatch', dispatchedEvent);

    while (true) {
      const commandInlineListeners = this.inlineListenersByCommandName[
        event.type
      ]
        ? this.inlineListenersByCommandName[event.type].get(currentTarget)
        : null;
      let listeners = commandInlineListeners || [];
      if (currentTarget.webkitMatchesSelector != null) {
        const selectorBasedListeners = (
          this.selectorBasedListenersByCommandName[event.type] || []
        )
          .filter(listener => listener.matchesTarget(currentTarget))
          .sort((a, b) => a.compare(b));
        listeners = selectorBasedListeners.concat(listeners);
      }

      // Call inline listeners first in reverse registration order,
      // and selector-based listeners by specificity and reverse
      // registration order.
      for (let i = listeners.length - 1; i >= 0; i--) {
        const listener = listeners[i];
        if (immediatePropagationStopped) {
          break;
        }
        matched.push(listener.didDispatch.call(currentTarget, dispatchedEvent));
      }

      if (currentTarget === window) {
        break;
      }
      if (propagationStopped) {
        break;
      }
      currentTarget = currentTarget.parentNode || window;
    }

    this.emitter.emit('did-dispatch', dispatchedEvent);

    return matched.length > 0 ? Promise.all(matched) : null;
  }

  commandRegistered(commandName) {
    if (this.rootNode != null && !this.registeredCommands[commandName]) {
      this.rootNode.addEventListener(
        commandName,
        this.handleCommandEvent,
        true
      );
      return (this.registeredCommands[commandName] = true);
    }
  }
};

// type Listener = {
//   descriptor: CommandDescriptor,
//   extractDidDispatch: (e: CustomEvent) => void,
// };
class SelectorBasedListener {
  constructor(selector, commandName, listener) {
    this.selector = selector;
    this.didDispatch = extractDidDispatch(listener);
    this.descriptor = extractDescriptor(commandName, listener);
    this.specificity = calculateSpecificity(this.selector);
    this.sequenceNumber = SequenceCount++;
  }

  compare(other) {
    return (
      this.specificity - other.specificity ||
      this.sequenceNumber - other.sequenceNumber
    );
  }

  matchesTarget(target) {
    return (
      target.webkitMatchesSelector &&
      target.webkitMatchesSelector(this.selector)
    );
  }
}

class InlineListener {
  constructor(commandName, listener) {
    this.didDispatch = extractDidDispatch(listener);
    this.descriptor = extractDescriptor(commandName, listener);
  }
}

// type CommandDescriptor = {
//   name: string,
//   displayName: string,
// };
function extractDescriptor(name, listener) {
  return Object.assign(_.omit(listener, 'didDispatch'), {
    name,
    displayName: listener.displayName
      ? listener.displayName
      : _.humanizeEventName(name)
  });
}

function extractDidDispatch(listener) {
  return typeof listener === 'function' ? listener : listener.didDispatch;
}