import { Cell } from "@nteract/presentational-components";

All by itself, this component doesn't do anything. Used with <Input />, <Source />, and <Outputs />, it brings styling to the children based on hover and selected states.

By moving a cursor over the component and hovering, styling can be changed.

A cell can be in one of three levels, similar to raised cards:

1. Flat on the "page"
2. Slight rise, mid way to fully active, while hovering (_hovered prop is true)
3. Raised up highest, when fully active (i.e. isSelected prop is true) -- the editor should be focused when this level is used

import { Cells } from "@nteract/presentational-components";

<Cells /> is a wrapper component to provide buffers between cells if you're building a notebook app.

The Input component is a container component that serves as a container for the Input of a cell.

import { Input } from "@nteract/presentational-components"

The Input component provides a hidden prop which you can use to dictate whether or not the children of the container are rendered. The default value is set to false, so you'll see the text "You can see this." rendered here.

Outputs is a container component for rendering the output of a particular cell. The output is response returned from the kernel as a result of the execution of a particular code cell.

import { Outputs } from "@nteract/presentational-components"

Similar to the Input component, the Outputs component exposes a hidden prop that you can use to determine whether or not to display the children of the presentational component. The hidden prop defaults to false, as you can see by viewing the source below.

Outputs also exposes an expanded flag which can be used to dictate whether the children of the container component should be collapsed or expanded to display all outputs. This is a useful prop to use when you want to limit or show the amount of information that is shown from large outputs. The expanded prop will default to false and collapse the contents of the cell.

You can use the expanded prop in conjunction with the collapsed property on cells within a Jupyter Notebook. This allows you to persist the state of an output and read from the persisted value.

When the expanded prop is set to false, you'll see an output like so.

You'll generally have both a Pagers component and an Outputs component as part of your notebook cell. Outputs typically contain calculation results or actions on a cell, and Pagers hold information, like help text, found from introspecting a cell.

import { Pagers } from "@nteract/presentational-components"

Similar to other components, the Pagers component provides a hidden flag that determines whether or not the contents of the component should be rendered. You can try it out below by toggling the value of the hidden prop in the code from false to true.

The Prompt component is typically a child of the Input component and serves two purposes. First, it serves as a visual indicator of input entry for end users. Secondly, it allows us to display relevant information about the state of a cell to the end user.

import { Prompt } from "@nteract/presentational-components"

A <Prompt/> component with no props will render an empty set of brackets.

The Source component is a container component that renders syntax highlighted source code.

import { Source } from "@nteract/presentational-components";

If the child component passed to Source is a string, it will automatically be rendered using nteract's internal source code highlighter.

To define the language that you'd like to use when highlighting source, you can use the language prop. Under the hood, the Source component uses the Prism syntax highlighter. You can view the full list of languages supported by this highlighter to determine what value you should pass to the language prop based on your needs.

You can pass the text/x-{languageName} format to the langauge prop. This is designed to make it easier to interact with the language_info.mimetype property contained in the Jupyter Notebook format.

You can use the className prop to add your own CSS-based styles to the highlighted source.

You can pass React component(s) inside of <Source /> to provide your own editor. For example, here we use a styled textarea to render some Python text.

NOTE: The notebook apps use this method to pass the Codemirror editor as the child.

Since this component is just a wrapper to keep styling consistent, you can pass all the onChange handlers you want to your own component.

The DisplayData component is a container component used to render rich media elements like images and HTML. This component acts as a simple switch on a set of rich media components. For example, we can define a component Plain that is responsible for rendering data with the text/plain media type and another component Smooth for rendering data with the text/smooth media type.

If you view the source, you'll notice that the component correctly rendered the text/plain data using the Plain component.

The ExecuteResult component is a container component that is used to render data returned by the kernel. The returned data may be in a number of output formats. Similar to the DisplayData component, the ExecuteResult component acts as a simple switch over its children and correctly associates the media type of the returned data with the media type that a component supports.

Why do so many component employ this pattern? It's in the interest of readability. Although each component executes the same logic under the hood, the separation of components by output types allows you to write meaningful JSX from these React components.

The <KernelOutputError /> component will render a Jupyter error, commonly done as a traceback. An old error style that is still sent by kernels is the ename and evalue. Per the Jupyter Messaging Protocol, the kernel will return the following payload if it encountered an error during the execution of a code cell.

{
   'status' : 'error',
   'ename' : string,
   'evalue' : string,
   'traceback' : string[],
}

The ename property contains the name of the error (OutOfMemory or NameError). The evalue property contains the value of the error. This is usually the first line you see before the complete traceback. The traceback property contains the stacktrace of the error as a list of strings, with each string consisting of a line within the stacktrace.

We provide a special KernelOutputError component that will allow you to render the error payloads received from the kernel. You can pass the ename, evalue, and traceback property values to render the error and traceback in a clean format.

Tracebacks usually include the ename and evalue at the bottom in python tracebacks. Hence we currently only render the traceback.

The Output element takes a single output prop and several child components and renders the appropriate components to render each output type.

For example, we can create a stream output and use the Output and StreamText components needed for each output type.

For further information on the <RichMedia /> component, keep reading! 👓 📚

Jupyter kernels are able to emit rich media like images, json, text, html, and many others. They're the core of what makes notebooks and consoles so expressive. They're sent over the jupyter messaging protocol and stored in the notebook just like this:

{
  "text/plain": "SparkContext ⚡️",
  "text/html": "<b>SparkContext ⚡️</b>",
  "application/json": {
    "spark": "awesome ⚡️",
    "version": 2
  }
}

This object structure is called a media bundle (formerly known as a mimebundle), so dubbed because it's a bundle of media types and associated data. Jupyter frontends pick the richest media type amongst these for rendering for the user, by selecting via a display order.

As an example, if the display order is:

["text/html", "application/json", "text/plain"]

Then the frontend will prefer HTML instead of JSON and JSON over plaintext. To render any one of these, we write a React Element that takes at least the prop data:

const Plain = props => <pre>{props.data}</pre>;

Plain.defaulProps = {
  mediaType: "text/plain"
};

They can also accept metadata if there is additional configuration allowed. Take for example images which allow setting the size via metadata:

const ImageMedia = props => (
  <img
    alt=""
    src={`data:${props.mediatype};base64,${props.data}`}
    {...props.metadata.size}
  />
);
ImageMedia.defaultProps = {
  mediaType: "image/png"
};

There are several different jupyter message types that include these objects:

• execute_result
• display_data and update_display_data
• inspect_reply
• payload's page

The <RichMedia /> component accepts the whole media bundle from a kernel via the data prop and all the elements for rendering media types as children. The order of the children states their richness from highest to lowest.

const Media = require('./media')

<RichMedia data={{ "text/plain": "SparkContext ⚡️" }}>
  <Media.HTML />
  <Media.Plain />
</RichMedia>

The <RichMedia /> component will pass the appropriate data from the media bundle to the element that accepts the media type. In this case, <Plain /> is picked as the richest since text/plain is the only available. "SparkContext ⚡️" is passed as <Plain data="SparkContext ⚡️" /> to render the richest media.

Since the children are React elements, we can pass custom props that will get rendered with the data:

The <RichMedia /> component comes with a built-in componentDidCatch fallback. To spare this style guide from being spammed with errors, we're not showing the error. To trigger it, uncomment the throw new Error line after clicking "View Code"

The Jupyter kernel will return outputs that contain data from standard out or standard error using the stream message type. The data contained in this messages consists of a string containing the contents of the output. To render these types of outputs from the kernel in your own Jupyter front-end, you can use the StreamText component.

The StreamText component takes a text prop which contains the contents of the stream. The name prop, which can be one of stdout or stderr dictates whether the text stream originated from standard out or standard error respectively.

The size of the image can be controlled by setting height and width in metadata. Python users typically do this with IPython.display.Image or by directly integrating with IPython's rich display handlers.

For example if a user displayed an image like this, we'd expect this output:

IPython.display.Image(data, height="132px", width="193px")

Then navigate to your browser's developer console and print out the value of the variable this_is_our_special_variable like so.

console.log(this_is_our_special_variable);
> 10

If you're familiar with the Jupyter ecosystem, note that this component executes JavaScript in a manner identical to Jupyter Notebook's JavaScript evaluation. The code you execute using this component will not persist through reloads, so it's a good place to test and iterate on scripts.

The Media.JavaScript component can also help you when things go wrong by printing an error trace. For example, here's what happens when you attempt to log invoke an undefined function.

JSON, or JavaScript Object Notation, is a popular data format that represents its contents in a human-readable form. JSON consists of a series of attribute value pairs, like name: "Tester McTester".

You can render JSON data into an explorable tree-like structure using the Media.Json component. JSON data is identified using the application/json media type.

SVG, or Scalable Vector Graphics, is an image format for two-dimensional graphics that support interactions and animations. SVGs are often represented as an XML-based format, similar to the format below.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<svg xmlns="http://www.w3.org/2000/svg" width="500" height="500">
<circle cx="250" cy="250" r="210" fill="#fff" stroke="#000" stroke-width="8"/>
</svg>

That's right! Under the hood, SVG images are just plain-text. Their scalability and responsiveness makes them great for rendering charts and graphs. The media type used to refer to SVGs in the Jupyter ecosystem, and elsewhere on the web, is image/svg+xml. To render SVGs, you can use the Media.SVG component. You'll need to pass a data prop that contains the plain-text contents of the SVG.

import { Entry } from "@nteract/directory-listing";

This component is used to create individual entries in a directory. It is not meant to be used alone, but rather as a child of the Listing component and renders children of its own. In nteract, we use it as the parent of the Icon, Name and LastSaved components in the nteract-on-jupyter and commuter applications.

In the example below, we use the Entry component to display an icon, name, and time since last save of an entry in a directory.

import { Icon } from "@nteract/directory-listing";

This component displays an icon for a particular file. The fileType prop can be one of "unknown", "notebook", "directory", "file", "dummy" to render the corresponding icon. Below are examples of each file type icon.

import { LastSaved } from "@nteract/directory-listing";

The LastSaved component displays the time since the date provide in lastModified in human readable format. The date provided to the lastModified prop should be a valid JavaScript date.

import {
  Entry,
  Listing,
  Icon,
  Name,
  LastSaved
} from "@nteract/directory-listing";

The Listing component is a container component to show any listing of directories and files in a tabular layout for users. This component works best with <Entry> for each item in a content listing.

import { Name } from "@nteract/directory-listing";

The Name is a container component can be used to show a stylized name of the file or directory in a listing. Generally, you'll want the child of this component to be a link to the path of the file that you'd like the user to click to open.