Add insertTab and defaultTabBinding

FEATURE: The new `insertTab` command inserts a tab when nothing is selected,
and defers to `indentMore` otherwise.

FEATURE: The package now exports a `defaultTabBinding` object that provides
a recommended binding for tab (if you must bind tab).

Issue codemirror/dev#238

src/README.md

@@ -9,6 +9,8 @@ with key bindings for a lot of them.
 
 @emacsStyleKeymap
 
+@defaultTabBinding
+
 ### Selection
 
 @simplifySelection
@@ -155,6 +157,8 @@ with key bindings for a lot of them.
 
 @indentLess
 
+@insertTab
+
 ### Character manipulation
 
 @transposeChars

src/commands.ts

@@ -597,6 +597,15 @@ export const indentLess: StateCommand = ({state, dispatch}) => {
   return true
 }
 
+/// Insert a tab character at the cursor or, if something is selected,
+/// use [`indentMore`](#commands.indentMore) to indent the entire
+/// selection.
+export const insertTab: StateCommand = ({state, dispatch}) => {
+  if (state.selection.ranges.some(r => !r.empty)) return indentMore({state, dispatch})
+  dispatch(state.update(state.replaceSelection("\t"), {scrollIntoView: true, annotations: Transaction.userEvent.of("input")}))
+  return true
+}
+
 /// Array of key bindings containing the Emacs-style bindings that are
 /// available on macOS by default.
 ///
@@ -753,3 +762,10 @@ export const defaultKeymap: readonly KeyBinding[] = ([
 
   {key: "Shift-Mod-\\", run: cursorMatchingBracket}
 ] as readonly KeyBinding[]).concat(standardKeymap)
+
+/// A binding that binds Tab to [`insertTab`](#commands.insertTab) and
+/// Shift-Tab to [`indentSelection`](#commands.indentSelection).
+/// Please see the [Tab example](../../examples/tab/) before using
+/// this.
+export const defaultTabBinding: KeyBinding =
+  {key: "Tab", run: insertTab, shift: indentSelection}