May 25, 2018 · Apr 23, 2018 · Apr 24, 2018 · Apr 25, 2018 · Apr 26, 2018 · Apr 27, 2018
diff --git a/docs/source/developer/documents.rst b/docs/source/developer/documents.rst
 Documents
 ---------

 JupyterLab can be extended intwo ways via:
 JupyterLab can be extended inseveral ways:

 -  Extensions (top level): Application extensions extend the
   functionality of JupyterLab itself, and we cover them in the
 For this section, the term 'document' refers to any visual thing that
 is backed by a file stored on disk (i.e. uses Contents API).

 Overview of document architecture
 ---------------------------------

 A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.imodel.html`__ interface. The model interface is intentionally fairly small, and concentrates on representing the data in the document and signaling changes to that data. Each model has an associated `context http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.icontext.html`__ instance as well. The context for a model is the bridge between the internal data of the document, stored in the model, and the file metadata and operations possible on the file, such as save and revert. Since many objects will need both the context and the model, the context contains a reference to the model as its `.model` attribute.

 A single file path can have multiple different models (and hence different contexts) representing the file. For example, a notebook can be opened with a notebook model and with a text model. Models for the same file path do not directly communicate with each other.

 `Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.html`__ represent a view of a document model. There can be multiple document widgets associated with a single document model, and they naturally stay in sync with each other since they are views on the same underlying data model.


 The `Document
 Registry <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html>`__
 is where document types and factories are registered. Plugins can

 *Document widget extensions* in the JupyterLab application can register:

 -  widget factories
 -  model factories
 -  widget extension factories
 -  file types
 -  model factories for specific file types
 -  widget factories for specific model factories
 -  widget extension factories
 -  file creators

 `Widget Factories <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html#addwidgetfactory>`__
diff --git a/examples/notebook/src/index.ts b/examples/notebook/src/index.ts
  let nbWidget = docManager.open(NOTEBOOK) as NotebookPanel;
  let palette = new CommandPalette({ commands });

  const editor = nbWidget.notebook.activeCell && nbWidget.notebook.activeCell.editor;
  const editor = nbWidget.content.activeCell && nbWidget.content.activeCell.editor;
  const model = new CompleterModel();
  const completer = new Completer({ editor, model });
  const connector = new KernelConnector({ session: nbWidget.session });
  handler.editor = editor;

  // Listen for active cell changes.
  nbWidget.notebook.activeCellChanged.connect((sender, cell) => {
  nbWidget.content.activeCellChanged.connect((sender, cell) => {
    handler.editor = cell && cell.editor;
  });

  commands.addCommand(cmdIds.invokeNotebook, {
    label: 'Invoke Notebook',
    execute: () => {
      if (nbWidget.notebook.activeCell.model.type === 'code') {
      if (nbWidget.content.activeCell.model.type === 'code') {
        return commands.execute(cmdIds.invoke);
      }
    }
  });
  commands.addCommand(cmdIds.selectNotebook, {
    label: 'Select Notebook',
    execute: () => {
      if (nbWidget.notebook.activeCell.model.type === 'code') {
      if (nbWidget.content.activeCell.model.type === 'code') {
        return commands.execute(cmdIds.select);
      }
    }
  commands.addCommand(cmdIds.runAndAdvance, {
    label: 'Run and Advance',
    execute: () => {
      NotebookActions.runAndAdvance(nbWidget.notebook, nbWidget.context.session);
      NotebookActions.runAndAdvance(nbWidget.content, nbWidget.context.session);
    }
  });
  commands.addCommand(cmdIds.editMode, {
    label: 'Edit Mode',
    execute: () => { nbWidget.notebook.mode = 'edit'; }
    execute: () => { nbWidget.content.mode = 'edit'; }
  });
  commands.addCommand(cmdIds.commandMode, {
    label: 'Command Mode',
    execute: () => { nbWidget.notebook.mode = 'command'; }
    execute: () => { nbWidget.content.mode = 'command'; }
  });
  commands.addCommand(cmdIds.selectBelow, {
    label: 'Select Below',
    execute: () => NotebookActions.selectBelow(nbWidget.notebook)
    execute: () => NotebookActions.selectBelow(nbWidget.content)
  });
  commands.addCommand(cmdIds.selectAbove, {
    label: 'Select Above',
    execute: () => NotebookActions.selectAbove(nbWidget.notebook)
    execute: () => NotebookActions.selectAbove(nbWidget.content)
  });
  commands.addCommand(cmdIds.extendAbove, {
    label: 'Extend Above',
    execute: () => NotebookActions.extendSelectionAbove(nbWidget.notebook)
    execute: () => NotebookActions.extendSelectionAbove(nbWidget.content)
  });
  commands.addCommand(cmdIds.extendBelow, {
    label: 'Extend Below',
    execute: () => NotebookActions.extendSelectionBelow(nbWidget.notebook)
    execute: () => NotebookActions.extendSelectionBelow(nbWidget.content)
  });
  commands.addCommand(cmdIds.merge, {
    label: 'Merge Cells',
    execute: () => NotebookActions.mergeCells(nbWidget.notebook)
    execute: () => NotebookActions.mergeCells(nbWidget.content)
  });
  commands.addCommand(cmdIds.split, {
    label: 'Split Cell',
    execute: () => NotebookActions.splitCell(nbWidget.notebook)
    execute: () => NotebookActions.splitCell(nbWidget.content)
  });
  commands.addCommand(cmdIds.undo, {
    label: 'Undo',
    execute: () => NotebookActions.undo(nbWidget.notebook)
    execute: () => NotebookActions.undo(nbWidget.content)
  });
  commands.addCommand(cmdIds.redo, {
    label: 'Redo',
    execute: () => NotebookActions.redo(nbWidget.notebook)
    execute: () => NotebookActions.redo(nbWidget.content)
  });

  let category = 'Notebook Operations';
diff --git a/packages/application/src/mimerenderers.ts b/packages/application/src/mimerenderers.ts
 } from '@jupyterlab/apputils';

 import {
 MimeDocument,MimeDocumentFactory, DocumentRegistry
  MimeDocumentFactory, DocumentRegistry, MimeDocument
 } from '@jupyterlab/docregistry';

 import {
diff --git a/packages/apputils/src/mainareawidget.ts b/packages/apputils/src/mainareawidget.ts
    this.title.changed.connect(this._updateContentTitle, this);
    content.disposed.connect(() => this.dispose());

    if (options.populated) {
    if (options.reveal) {
      layout.addWidget(spinner);
      this.populated = options.populated;
      this.populated.then(() => {
        this._isPopulated = true;
      // Make sure the ready promise is a Promise<void> to avoid leaking any
      // results.
      this._reveal = options.reveal.then(() => {
        this._isRevealed = true;
        const active = document.activeElement === spinner.node;
        spinner.dispose();
        layout.addWidget(content);
        BoxLayout.setStretch(error, 1);
        spinner.dispose();
        layout.addWidget(error);
        throw(error);
      });
    // Handle no populated promise.
    } else {
      spinner.dispose();
      layout.addWidget(content);
      this._isPopulated = true;
      this.populated = Promise.resolve(void 0);
      this._isRevealed = true;
      this._reveal = Promise.resolve(undefined);
    }
  }

  readonly toolbar: Toolbar;

  /**
   * Whether the widget isfully populated.
   * Whether the widget isrevealed.
   */
  getisPopulated(): boolean {
    return this._isPopulated;
  getisRevealed(): boolean {
    return this._isRevealed;
  }

  /**
   * A promise that resolves when the widget isfully populated.
   * A promise that resolves when the widget isready to be revealed.
   */
  readonly populated: Promise<void>;
  get reveal(): Promise<void> {
    return this._reveal;
  }

  /**
   * Handle the DOM events for the widget.
    case 'mouseup':
    case 'mouseout':
      let target = event.target as HTMLElement;
      if (this._isPopulated &&
      if (this._isRevealed &&
          this.toolbar.node.contains(document.activeElement) &&
          target.tagName !== 'SELECT') {
        this._focusContent();
   * Handle `'activate-request'` messages.
   */
  protected onActivateRequest(msg: Message): void {
    if (this._isPopulated) {
    if (this._isRevealed) {
      this._focusContent();
    } else {
      this._spinner.node.focus();
   * Give focus to the content.
   */
  private _focusContent(): void {
    // Focus the content node if we aren't already focused on it or a
    // descendent.
    if (!this.content.node.contains(document.activeElement)) {
      this.content.node.focus();
    }
    // Give the content a chance to activate.

    // Activate the content asynchronously (which may change the focus).
    this.content.activate();
  }

  private _changeGuard = false;
  private _isPopulated = false;
  private _spinner = new Spinner();

  private _isRevealed = false;
  private _reveal: Promise<void>;
 }


    toolbar?: Toolbar;

    /**
     * An optional promise for when the content is fully populated.
     * An optional promise for when the content is ready to be revealed.
     */
    reveal?: Promise<any>;
  }

  /**
   * An options object for main area widget subclasses providing their own
   * default content.
   *
   * #### Notes
   * This makes it easier to have a subclass that provides its own default
   * content. This can go away once we upgrade to TypeScript 2.8 and have an
   * easy way to make a single property optional, ala
   * https://stackoverflow.com/a/46941824
   */
  export
  interface IOptionsOptionalContent<T extends Widget = Widget> extends Widget.IOptions {
    /**
     * The child widget to wrap.
     */
    content?: T;

    /**
     * The toolbar to use for the widget.  Defaults to an empty toolbar.
     */
    toolbar?: Toolbar;

    /**
     * An optional promise for when the content is ready to be revealed.
     */
 populated?: Promise<void>;
 reveal?: Promise<any>;
  }

 }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -3,7 +3,7 @@
		Documents
		---------

		JupyterLab can be extended intwo ways via:
		JupyterLab can be extended inseveral ways:

		- Extensions (top level): Application extensions extend the
		functionality of JupyterLab itself, and we cover them in the
Expand All		@@ -15,6 +15,16 @@ JupyterLab can be extended in two ways via:
		For this section, the term 'document' refers to any visual thing that
		is backed by a file stored on disk (i.e. uses Contents API).

		Overview of document architecture
		---------------------------------

		A 'document' in JupyterLab is represented by a model instance implementing the `IModel http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.imodel.html`__ interface. The model interface is intentionally fairly small, and concentrates on representing the data in the document and signaling changes to that data. Each model has an associated `context http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.icontext.html`__ instance as well. The context for a model is the bridge between the internal data of the document, stored in the model, and the file metadata and operations possible on the file, such as save and revert. Since many objects will need both the context and the model, the context contains a reference to the model as its `.model` attribute.

		A single file path can have multiple different models (and hence different contexts) representing the file. For example, a notebook can be opened with a notebook model and with a text model. Models for the same file path do not directly communicate with each other.
Copy link Member ian-r-roseMay 24, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. I thought this sentence was kind of misleading. File views sharing the same modeldo communicate with each other. Perhaps "Different models for the same file path"? Copy link ContributorAuthor jasongroutMay 24, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Sure.

		`Document widgets http://jupyterlab.github.io/jupyterlab/interfaces/_docregistry_src_registry_.documentregistry.ireadywidget.html`__ represent a view of a document model. There can be multiple document widgets associated with a single document model, and they naturally stay in sync with each other since they are views on the same underlying data model.


		The `Document
		Registry <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html>`__
		is where document types and factories are registered. Plugins can
Expand All		@@ -32,10 +42,10 @@ Document Registry

		Document widget extensions in the JupyterLab application can register:

		- widget factories
		- model factories
		- widget extension factories
		- file types
		- model factories for specific file types
		- widget factories for specific model factories
		- widget extension factories
		- file creators

		`Widget Factories <http://jupyterlab.github.io/jupyterlab/classes/_docregistry_src_registry_.documentregistry.html#addwidgetfactory>`__
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -125,7 +125,7 @@ function createApp(manager: ServiceManager.IManager): void {
		let nbWidget = docManager.open(NOTEBOOK) as NotebookPanel;
		let palette = new CommandPalette({ commands });

		const editor = nbWidget.notebook.activeCell && nbWidget.notebook.activeCell.editor;
		const editor = nbWidget.content.activeCell && nbWidget.content.activeCell.editor;
		const model = new CompleterModel();
		const completer = new Completer({ editor, model });
		const connector = new KernelConnector({ session: nbWidget.session });
Expand All		@@ -135,7 +135,7 @@ function createApp(manager: ServiceManager.IManager): void {
		handler.editor = editor;

		// Listen for active cell changes.
		nbWidget.notebook.activeCellChanged.connect((sender, cell) => {
		nbWidget.content.activeCellChanged.connect((sender, cell) => {
		handler.editor = cell && cell.editor;
		});

Expand DownExpand Up		@@ -170,15 +170,15 @@ function createApp(manager: ServiceManager.IManager): void {
		commands.addCommand(cmdIds.invokeNotebook, {
		label: 'Invoke Notebook',
		execute: () => {
		if (nbWidget.notebook.activeCell.model.type === 'code') {
		if (nbWidget.content.activeCell.model.type === 'code') {
		return commands.execute(cmdIds.invoke);
		}
		}
		});
		commands.addCommand(cmdIds.selectNotebook, {
		label: 'Select Notebook',
		execute: () => {
		if (nbWidget.notebook.activeCell.model.type === 'code') {
		if (nbWidget.content.activeCell.model.type === 'code') {
		return commands.execute(cmdIds.select);
		}
		}
Expand DownExpand Up		@@ -206,48 +206,48 @@ function createApp(manager: ServiceManager.IManager): void {
		commands.addCommand(cmdIds.runAndAdvance, {
		label: 'Run and Advance',
		execute: () => {
		NotebookActions.runAndAdvance(nbWidget.notebook, nbWidget.context.session);
		NotebookActions.runAndAdvance(nbWidget.content, nbWidget.context.session);
		}
		});
		commands.addCommand(cmdIds.editMode, {
		label: 'Edit Mode',
		execute: () => { nbWidget.notebook.mode = 'edit'; }
		execute: () => { nbWidget.content.mode = 'edit'; }
		});
		commands.addCommand(cmdIds.commandMode, {
		label: 'Command Mode',
		execute: () => { nbWidget.notebook.mode = 'command'; }
		execute: () => { nbWidget.content.mode = 'command'; }
		});
		commands.addCommand(cmdIds.selectBelow, {
		label: 'Select Below',
		execute: () => NotebookActions.selectBelow(nbWidget.notebook)
		execute: () => NotebookActions.selectBelow(nbWidget.content)
		});
		commands.addCommand(cmdIds.selectAbove, {
		label: 'Select Above',
		execute: () => NotebookActions.selectAbove(nbWidget.notebook)
		execute: () => NotebookActions.selectAbove(nbWidget.content)
		});
		commands.addCommand(cmdIds.extendAbove, {
		label: 'Extend Above',
		execute: () => NotebookActions.extendSelectionAbove(nbWidget.notebook)
		execute: () => NotebookActions.extendSelectionAbove(nbWidget.content)
		});
		commands.addCommand(cmdIds.extendBelow, {
		label: 'Extend Below',
		execute: () => NotebookActions.extendSelectionBelow(nbWidget.notebook)
		execute: () => NotebookActions.extendSelectionBelow(nbWidget.content)
		});
		commands.addCommand(cmdIds.merge, {
		label: 'Merge Cells',
		execute: () => NotebookActions.mergeCells(nbWidget.notebook)
		execute: () => NotebookActions.mergeCells(nbWidget.content)
		});
		commands.addCommand(cmdIds.split, {
		label: 'Split Cell',
		execute: () => NotebookActions.splitCell(nbWidget.notebook)
		execute: () => NotebookActions.splitCell(nbWidget.content)
		});
		commands.addCommand(cmdIds.undo, {
		label: 'Undo',
		execute: () => NotebookActions.undo(nbWidget.notebook)
		execute: () => NotebookActions.undo(nbWidget.content)
		});
		commands.addCommand(cmdIds.redo, {
		label: 'Redo',
		execute: () => NotebookActions.redo(nbWidget.notebook)
		execute: () => NotebookActions.redo(nbWidget.content)
		});

		let category = 'Notebook Operations';
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,7 +6,7 @@ import {
		} from '@jupyterlab/apputils';

		import {
		MimeDocument,MimeDocumentFactory, DocumentRegistry
		MimeDocumentFactory, DocumentRegistry, MimeDocument
		} from '@jupyterlab/docregistry';

		import {
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -67,11 +67,12 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		this.title.changed.connect(this._updateContentTitle, this);
		content.disposed.connect(() => this.dispose());

		if (options.populated) {
		if (options.reveal) {
		layout.addWidget(spinner);
		this.populated = options.populated;
		this.populated.then(() => {
		this._isPopulated = true;
		// Make sure the ready promise is a Promise<void> to avoid leaking any
		// results.
		this._reveal = options.reveal.then(() => {
		this._isRevealed = true;
		const active = document.activeElement === spinner.node;
		spinner.dispose();
		layout.addWidget(content);
Expand All		@@ -88,13 +89,14 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		BoxLayout.setStretch(error, 1);
		spinner.dispose();
		layout.addWidget(error);
		throw(error);
		});
		// Handle no populated promise.
		} else {
		spinner.dispose();
		layout.addWidget(content);
		this._isPopulated = true;
		this.populated = Promise.resolve(void 0);
		this._isRevealed = true;
		this._reveal = Promise.resolve(undefined);
		}
		}

Expand All		@@ -109,16 +111,18 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		readonly toolbar: Toolbar;

		/**
		* Whether the widget isfully populated.
		* Whether the widget isrevealed.
		*/
		getisPopulated(): boolean {
		return this._isPopulated;
		getisRevealed(): boolean {
		return this._isRevealed;
		}

		/**
		* A promise that resolves when the widget isfully populated.
		* A promise that resolves when the widget isready to be revealed.
		*/
		readonly populated: Promise<void>;
		get reveal(): Promise<void> {
		return this._reveal;
		}

		/**
		* Handle the DOM events for the widget.
Expand All		@@ -135,7 +139,7 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		case 'mouseup':
		case 'mouseout':
		let target = event.target as HTMLElement;
		if (this._isPopulated &&
		if (this._isRevealed &&
		this.toolbar.node.contains(document.activeElement) &&
		target.tagName !== 'SELECT') {
		this._focusContent();
Expand DownExpand Up		@@ -166,7 +170,7 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		* Handle `'activate-request'` messages.
		*/
		protected onActivateRequest(msg: Message): void {
		if (this._isPopulated) {
		if (this._isRevealed) {
		this._focusContent();
		} else {
		this._spinner.node.focus();
Expand DownExpand Up		@@ -222,16 +226,21 @@ class MainAreaWidget<T extends Widget = Widget> extends Widget {
		* Give focus to the content.
		*/
		private _focusContent(): void {
		// Focus the content node if we aren't already focused on it or a
		// descendent.
		if (!this.content.node.contains(document.activeElement)) {
		this.content.node.focus();
		}
		// Give the content a chance to activate.

		// Activate the content asynchronously (which may change the focus).
		this.content.activate();
		}

		private _changeGuard = false;
		private _isPopulated = false;
		private _spinner = new Spinner();

		private _isRevealed = false;
		private _reveal: Promise<void>;
		}


Expand All		@@ -256,8 +265,37 @@ namespace MainAreaWidget {
		toolbar?: Toolbar;

		/**
		* An optional promise for when the content is fully populated.
		* An optional promise for when the content is ready to be revealed.
		*/
		reveal?: Promise<any>;
		}

		/**
		* An options object for main area widget subclasses providing their own
		* default content.
		*
		* #### Notes
		* This makes it easier to have a subclass that provides its own default
		* content. This can go away once we upgrade to TypeScript 2.8 and have an
		* easy way to make a single property optional, ala
		* https://stackoverflow.com/a/46941824
		*/
		export
		interface IOptionsOptionalContent<T extends Widget = Widget> extends Widget.IOptions {
		/**
		* The child widget to wrap.
		*/
		content?: T;
Copy link Member ian-r-roseMay 22, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. What is your current thinking on ownership issues for the content of a`MainAreaWidget`? When this is passed in, does ownership transfer to the main area widget, or does it stick with the`new` caller? Copy link ContributorAuthor jasongroutMay 23, 2018 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. It has to transfer ownership to the MainAreaWidget. In phosphor, widgets reparent/own their children, dispose their children, move their children in the DOM to be under them, etc.

		/**
		* The toolbar to use for the widget. Defaults to an empty toolbar.
		*/
		toolbar?: Toolbar;

		/**
		* An optional promise for when the content is ready to be revealed.
		*/
		populated?: Promise<void>;
		reveal?: Promise<any>;
		}

		}