Merge pull request #3469 from atom/ns-command-registry

Add command registry

package.json

@@ -78,7 +78,7 @@
     "background-tips": "0.16.0",
     "bookmarks": "0.28.0",
     "bracket-matcher": "0.55.0",
-    "command-palette": "0.24.0",
+    "command-palette": "0.25.0",
     "deprecation-cop": "0.10.0",
     "dev-live-reload": "0.34.0",
     "exception-reporting": "0.20.0",

spec/command-registry-spec.coffee

@@ -0,0 +1,126 @@
+CommandRegistry = require '../src/command-registry'
+
+describe "CommandRegistry", ->
+  [registry, parent, child, grandchild] = []
+
+  beforeEach ->
+    parent = document.createElement("div")
+    child = document.createElement("div")
+    grandchild = document.createElement("div")
+    parent.classList.add('parent')
+    child.classList.add('child')
+    grandchild.classList.add('grandchild')
+    child.appendChild(grandchild)
+    parent.appendChild(child)
+    document.querySelector('#jasmine-content').appendChild(parent)
+
+    registry = new CommandRegistry(parent)
+
+  describe "command dispatch", ->
+    it "invokes callbacks with selectors matching the target", ->
+      called = false
+      registry.add '.grandchild', 'command', (event) ->
+        expect(this).toBe grandchild
+        expect(event.type).toBe 'command'
+        expect(event.eventPhase).toBe Event.BUBBLING_PHASE
+        expect(event.target).toBe grandchild
+        expect(event.currentTarget).toBe grandchild
+        called = true
+
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(called).toBe true
+
+    it "invokes callbacks with selectors matching ancestors of the target", ->
+      calls = []
+
+      registry.add '.child', 'command', (event) ->
+        expect(this).toBe child
+        expect(event.target).toBe grandchild
+        expect(event.currentTarget).toBe child
+        calls.push('child')
+
+      registry.add '.parent', 'command', (event) ->
+        expect(this).toBe parent
+        expect(event.target).toBe grandchild
+        expect(event.currentTarget).toBe parent
+        calls.push('parent')
+
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual ['child', 'parent']
+
+    it "orders multiple matching listeners for an element by selector specificity", ->
+      child.classList.add('foo', 'bar')
+      calls = []
+
+      registry.add '.foo.bar', 'command', -> calls.push('.foo.bar')
+      registry.add '.foo', 'command', -> calls.push('.foo')
+      registry.add '.bar', 'command', -> calls.push('.bar') # specificity ties favor commands added later, like CSS
+
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual ['.foo.bar', '.bar', '.foo']
+
+    it "stops bubbling through ancestors when .stopPropagation() is called on the event", ->
+      calls = []
+
+      registry.add '.parent', 'command', -> calls.push('parent')
+      registry.add '.child', 'command', -> calls.push('child-2')
+      registry.add '.child', 'command', (event) -> calls.push('child-1'); event.stopPropagation()
+
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual ['child-1', 'child-2']
+
+    it "stops invoking callbacks when .stopImmediatePropagation() is called on the event", ->
+      calls = []
+
+      registry.add '.parent', 'command', -> calls.push('parent')
+      registry.add '.child', 'command', -> calls.push('child-2')
+      registry.add '.child', 'command', (event) -> calls.push('child-1'); event.stopImmediatePropagation()
+
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual ['child-1']
+
+    it "allows listeners to be removed via a disposable returned by ::add", ->
+      calls = []
+
+      disposable1 = registry.add '.parent', 'command', -> calls.push('parent')
+      disposable2 = registry.add '.child', 'command', -> calls.push('child')
+
+      disposable1.dispose()
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual ['child']
+
+      calls = []
+      disposable2.dispose()
+      grandchild.dispatchEvent(new CustomEvent('command', bubbles: true))
+      expect(calls).toEqual []
+
+    it "allows multiple commands to be registered under one selector when called with an object", ->
+      calls = []
+
+      disposable = registry.add '.child',
+        'command-1': -> calls.push('command-1')
+        'command-2': -> calls.push('command-2')
+
+      grandchild.dispatchEvent(new CustomEvent('command-1', bubbles: true))
+      grandchild.dispatchEvent(new CustomEvent('command-2', bubbles: true))
+
+      expect(calls).toEqual ['command-1', 'command-2']
+
+      calls = []
+      disposable.dispose()
+      grandchild.dispatchEvent(new CustomEvent('command-1', bubbles: true))
+      grandchild.dispatchEvent(new CustomEvent('command-2', bubbles: true))
+      expect(calls).toEqual []
+
+  describe "::findCommands({target})", ->
+    it "returns commands that can be invoked on the target or its ancestors", ->
+      registry.add '.parent', 'namespace:command-1', ->
+      registry.add '.child', 'namespace:command-2', ->
+      registry.add '.grandchild', 'namespace:command-3', ->
+      registry.add '.grandchild.no-match', 'namespace:command-4', ->
+
+      expect(registry.findCommands(target: grandchild)[0..2]).toEqual [
+        {name: 'namespace:command-3', displayName: 'Namespace: Command 3'}
+        {name: 'namespace:command-2', displayName: 'Namespace: Command 2'}
+        {name: 'namespace:command-1', displayName: 'Namespace: Command 1'}
+      ]

spec/spec-helper.coffee

@@ -64,6 +64,7 @@ beforeEach ->
   atom.project = new Project(path: projectPath)
   atom.workspace = new Workspace()
   atom.keymaps.keyBindings = _.clone(keyBindingsToRestore)
+  atom.commands.setRootNode(document.body)
 
   window.resetTimeouts()
   atom.packages.packageStates = {}
@@ -120,6 +121,8 @@ beforeEach ->
   addCustomMatchers(this)
 
 afterEach ->
+  atom.commands.clear()
+
   atom.packages.deactivatePackages()
   atom.menu.template = []
 

src/atom.coffee

@@ -113,6 +113,9 @@ class Atom extends Model
   # Public: A {KeymapManager} instance
   keymaps: null
 
+  # Public: A {CommandRegistry} instance
+  commands: null
+
   # Public: A {MenuManager} instance
   menu: null
 
@@ -158,6 +161,7 @@ class Atom extends Model
 
     Config = require './config'
     KeymapManager = require './keymap-extensions'
+    CommandRegistry = require './command-registry'
     PackageManager = require './package-manager'
     Clipboard = require './clipboard'
     Syntax = require './syntax'
@@ -179,6 +183,7 @@ class Atom extends Model
     @config = new Config({configDirPath, resourcePath})
     @keymaps = new KeymapManager({configDirPath, resourcePath})
     @keymap = @keymaps # Deprecated
+    @commands = new CommandRegistry
     @packages = new PackageManager({devMode, configDirPath, resourcePath, safeMode})
     @themes = new ThemeManager({packageManager: @packages, configDirPath, resourcePath, safeMode})
     @contextMenu = new ContextMenuManager({resourcePath, devMode})

src/command-registry.coffee

@@ -0,0 +1,178 @@
+{Disposable, CompositeDisposable} = require 'event-kit'
+{specificity} = require 'clear-cut'
+_ = require 'underscore-plus'
+{$} = require './space-pen-extensions'
+
+SequenceCount = 0
+SpecificityCache = {}
+
+module.exports =
+
+# Experimental: 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.
+#
+# 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 '.editor',
+#   'user:insert-date': (event) ->
+#     editor = $(this).view().getModel()
+#     # soon the above above line will be:
+#     # editor = @getModel()
+#     editor.insertText(new Date().toLocaleString())
+# ```
+class CommandRegistry
+  constructor: (@rootNode) ->
+    @listenersByCommandName = {}
+
+  setRootNode: (newRootNode) ->
+    oldRootNode = @rootNode
+    @rootNode = newRootNode
+
+    for commandName of @listenersByCommandName
+      oldRootNode?.removeEventListener(commandName, @dispatchCommand, true)
+      newRootNode?.addEventListener(commandName, @dispatchCommand, true)
+
+  # Public: Add one or more command listeners associated with a selector.
+  #
+  # ## Arguments: Registering One Command
+  #
+  # * `selector` A {String} containing a CSS selector matching elements on which
+  #   you want to handle the commands. The `,` combinator is not currently
+  #   supported.
+  # * `commandName` A {String} containing the name of a command you want to
+  #   handle such as `user:insert-date`.
+  # * `callback` A {Function} to call when the given command is invoked on an
+  #   element matching the selector. It will be called with `this` referencing
+  #   the matching DOM node.
+  #   * `event` A standard DOM event instance. Call `stopPropagation` or
+  #     `stopImmediatePropagation` to terminate bubbling early.
+  #
+  # ## Arguments: Registering Multiple Commands
+  #
+  # * `selector` A {String} containing a CSS selector matching elements on which
+  #   you want to handle the commands. The `,` combinator is not currently
+  #   supported.
+  # * `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: (selector, commandName, callback) ->
+    if typeof commandName is 'object'
+      commands = commandName
+      disposable = new CompositeDisposable
+      for commandName, callback of commands
+        disposable.add @add(selector, commandName, callback)
+      return disposable
+
+    unless @listenersByCommandName[commandName]?
+      @rootNode?.addEventListener(commandName, @dispatchCommand, true)
+      @listenersByCommandName[commandName] = []
+
+    listener = new CommandListener(selector, callback)
+    listenersForCommand = @listenersByCommandName[commandName]
+    listenersForCommand.push(listener)
+
+    new Disposable =>
+      listenersForCommand.splice(listenersForCommand.indexOf(listener), 1)
+      if listenersForCommand.length is 0
+        delete @listenersByCommandName[commandName]
+        @rootNode.removeEventListener(commandName, @dispatchCommand, true)
+
+  dispatchCommand: (event) =>
+    propagationStopped = false
+    immediatePropagationStopped = false
+    currentTarget = event.target
+
+    syntheticEvent = Object.create event,
+      eventPhase: value: Event.BUBBLING_PHASE
+      currentTarget: get: -> currentTarget
+      stopPropagation: value: ->
+        propagationStopped = true
+      stopImmediatePropagation: value: ->
+        propagationStopped = true
+        immediatePropagationStopped = true
+
+    loop
+      matchingListeners =
+        @listenersByCommandName[event.type]
+          .filter (listener) -> currentTarget.webkitMatchesSelector(listener.selector)
+          .sort (a, b) -> a.compare(b)
+
+      for listener in matchingListeners
+        break if immediatePropagationStopped
+        listener.callback.call(currentTarget, syntheticEvent)
+
+      break if propagationStopped
+      break if currentTarget is @rootNode
+      currentTarget = currentTarget.parentNode
+
+  # 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 {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`.
+  #  * `jQuery` Present if the command was registered with the legacy
+  #    `$::command` method.
+  findCommands: ({target}) ->
+    commands = []
+    target = @rootNode unless @rootNode.contains(target)
+    currentTarget = target
+    loop
+      for commandName, listeners of @listenersByCommandName
+        for listener in listeners
+          if currentTarget.webkitMatchesSelector(listener.selector)
+            commands.push
+              name: commandName
+              displayName: _.humanizeEventName(commandName)
+
+      break if currentTarget is @rootNode
+      currentTarget = currentTarget.parentNode
+
+    for name, displayName of $(target).events() when displayName
+      commands.push({name, displayName, jQuery: true})
+
+    for name, displayName of $(window).events() when displayName
+      commands.push({name, displayName, jQuery: true})
+
+    commands
+
+  clear: ->
+    @listenersByCommandName = {}
+
+class CommandListener
+  constructor: (@selector, @callback) ->
+    console.log "calc specificity", @selector
+
+    @specificity = (SpecificityCache[@selector] ?= specificity(@selector))
+    @sequenceNumber = SequenceCount++
+
+  compare: (other) ->
+    other.specificity - @specificity  or
+      other.sequenceNumber - @sequenceNumber

src/workspace-view.coffee

@@ -15,6 +15,11 @@ PaneRowView = require './pane-row-view'
 PaneContainerView = require './pane-container-view'
 Editor = require './editor'
 
+atom.commands.add '.workspace',
+  'window:increase-font-size': -> @getModel().increaseFontSize()
+  'window:decrease-font-size': -> @getModel().decreaseFontSize()
+  'window:reset-font-size': -> @getModel().resetFontSize()
+
 # Essential: The top-level view for the entire window. An instance of this class is
 # available via the `atom.workspaceView` global.
 #
@@ -77,8 +82,10 @@ class WorkspaceView extends View
         @div class: 'vertical', outlet: 'vertical', =>
           @div class: 'panes', outlet: 'panes'
 
-  initialize: (@model) ->
-    @model = atom.workspace ? new Workspace unless @model?
+  initialize: (model) ->
+    @model = model ? atom.workspace ? new Workspace unless @model?
+    @element.getModel = -> model
+    atom.commands.setRootNode(@[0])
 
     panes = new PaneContainerView(@model.paneContainer)
     @panes.replaceWith(panes)
@@ -140,9 +147,6 @@ class WorkspaceView extends View
       @command 'window:install-shell-commands', => @installShellCommands()
 
     @command 'window:run-package-specs', -> ipc.send('run-package-specs', path.join(atom.project.getPath(), 'spec'))
-    @command 'window:increase-font-size', => @increaseFontSize()
-    @command 'window:decrease-font-size', => @decreaseFontSize()
-    @command 'window:reset-font-size', => @model.resetFontSize()
 
     @command 'window:focus-next-pane', => @focusNextPaneView()
     @command 'window:focus-previous-pane', => @focusPreviousPaneView()