Specs

control() :: {:control, attrs :: control_attrs()}

A control widget.

All controls have the following properties:

• :type - one of the recognised control types

• :ref - a unique identifier

• :destination - the process to send event messages to

On top of that, each control type may have additional attributes.

Events

All control events are sent to :destination as {:event, id, info}, where info is a map including additional details. In particular, it always includes :origin, which is an opaque identifier of the client that triggered the event.

Specs

control_attrs() ::
  %{
    type: :keyboard,
    ref: ref(),
    destination: Process.dest(),
    events: [:keyup | :keydown | :status]
  }
  | %{type: :button, ref: ref(), destination: Process.dest(), label: String.t()}
  | %{
      type: :form,
      ref: ref(),
      destination: Process.dest(),
      fields: [{field :: atom(), input_attrs()}],
      submit: String.t() | nil,
      report_changes: %{required(field :: atom()) => true},
      reset_on_submit: [field :: atom()]
    }

Specs

frame() :: {:frame, outputs :: [t()], frame_info()}

Outputs placeholder.

Frame with type :default includes the initial list of outputs. Other types can be used to update outputs within the given frame.

In all cases the outputs order is reversed, that is, most recent outputs are at the top of the stack.

Specs

frame_info() :: %{ref: frame_ref(), type: :default | :replace | :append}

Specs

frame_ref() :: String.t()

Specs

ignored() :: :ignored

An empty output that should be ignored whenever encountered.

Specs

image() :: {:image, content :: binary(), mime_type :: binary()}

A raw image in the given format.

Specs

input() :: {:input, attrs :: input_attrs()}

An input field.

All inputs have the following properties:

• :type - one of the recognised input types

• :ref - a unique identifier

• :id - a persistent input identifier, the same on every reevaluation

• :label - an arbitrary text used as the input caption

• :default - the initial input value

• :destination - the process to send event messages to

On top of that, each input type may have additional attributes.

Specs

input_attrs() ::
  %{
    type: :text,
    ref: ref(),
    id: input_id(),
    label: String.t(),
    default: String.t(),
    destination: Process.dest()
  }
  | %{
      type: :textarea,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: String.t(),
      destination: Process.dest()
    }
  | %{
      type: :password,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: String.t(),
      destination: Process.dest()
    }
  | %{
      type: :number,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: number() | nil,
      destination: Process.dest()
    }
  | %{
      type: :url,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: String.t() | nil,
      destination: Process.dest()
    }
  | %{
      type: :select,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: term(),
      destination: Process.dest(),
      options: [{value :: term(), label :: String.t()}]
    }
  | %{
      type: :checkbox,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: boolean(),
      destination: Process.dest()
    }
  | %{
      type: :range,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: number(),
      destination: Process.dest(),
      min: number(),
      max: number(),
      step: number()
    }
  | %{
      type: :color,
      ref: ref(),
      id: input_id(),
      label: String.t(),
      default: String.t(),
      destination: Process.dest()
    }

Specs

input_id() :: String.t()

Specs

js() :: {:js, info :: js_info()}

JavaScript powered output with dynamic data and events.

This output points to a server process that serves data requests and sends custom events.

Communication protocol

A client process should connect to the server process by sending:

{:connect, pid(), info :: %{ref: ref(), origin: term()}}

And expect the following reply:

{:connect_reply, initial_data, info :: %{ref: ref()}}

The server process may then keep sending one of the following events:

{:event, event :: String.t(), payload :: term(), info :: %{ref: ref()}}

The client process may keep sending one of the following events:

{:event, event :: String.t(), payload :: term(), info :: %{ref: ref(), origin: term()}}

See Kino.JS and Kino.JS.Live for more details.

Specs

js_info() :: %{
  ref: ref(),
  pid: Process.dest(),
  assets: %{archive_path: String.t(), hash: String.t(), js_path: String.t()},
  export: nil | %{info_string: String.t(), key: nil | term()}
}

Data describing a custom JS output component.

• :ref - unique output identifier

• :pid - the server process holding the data

Assets

The :assets map includes information about the relevant files.

• :archive_path - an absolute path to a .tar.gz archive with all the assets

• :hash - a checksum of all assets in the archive

• :js_path - a relative asset path pointing to the JavaScript entrypoint module

Export

The :export map describes how the output should be persisted. The output data is put in a Markdown fenced code block.

• :info_string - used as the info string for the Markdown code block

• :key - in case the data is a map and only a specific part should be exported

Specs

markdown() :: {:markdown, binary()}

Markdown content.

Specs

ref() :: String.t()

Specs

stdout() :: {:stdout, binary()}

IO text output, adjacent such outputs are treated as a whole

Specs

t() ::
  ignored()
  | stdout()
  | text()
  | markdown()
  | image()
  | js()
  | frame()
  | input()
  | control()

Livebook cell output may be one of these values and gets rendered accordingly.

Specs

text() :: {:text, binary()}

Standalone text block.