Richly Typed Hypermedia

Consider the proposed output of a WebTerminal command like ls (discussed in Structured Data):

[
  {
    name: path::"a.txt",
    type: filetype::"file",
    size: bytes::1234,
    modified: 2001-01-01T
  },
  {
    name: path::"b.txt",
    type: filetype::"file",
    size: bytes::4567,
    modified: 2002-02-02T
  }, // ...
]

We’d like to display this data to the user as an HTML table, with contents like:

name type size modified
a.txt file 1 KiB 3 years ago
b.txt file 4 KiB 2 years ago
d directory 8 KiB 1 year ago

Data Formats

File Paths

In the WebTerminal environment, strings with the path:: annotation represent files on disk. By employing this annotation, programs can unambiguously express file names in their output; and the WebTerminal UI will react to it and provide an intelligent experience.

When rendering a value like path::"foo.txt" for display as HTML, WebTerminal might employ data-* microformats to capture the file’s absolute path, and/or the current working directory when the path was produced as output. For example, if the user’s current working directory is /users/alice, and a program produces a filename as output like path::"foo.txt", then WebTerminal might render this in HTML as:

<span class="path"
  data-cwd="/users/alice/"
  data-abs-path="/users/alice/foo.txt">
  foo.txt
</span>

The element has a unique class="path" which is applied to path:: values. It also has an element data-cwd= capturing the current working directory when the path was produced, as well as a data-abs-path= capturing the file’s absolute path.

Since files are displayed with class="path", the UI can intelligently style the element and display actions relevant to files, such as:

  1. Copy as relative path (./foo.txt)
  2. Copy as absolute path (/users/alice/foo.txt)
  3. Open the file using $EDITOR
  4. Navigate to the file
  5. An extended mouse-over of the file name might display a brief preview of the file contents

Even if the user changes their working directory, these functions will still operate correctly.

File Size

WebTerminal will take advantage of the bytes annotation on file sizes, e.g. size: bytes::1048576, to display the value in a human-readable way. For example, when a program outputs a value like size: bytes::1048576, then WebTerminal might render it as the human-readable 1 MiB using the following HTML:

<span class="size"
  data-raw="1048576">
  1 MiB
</span>

This HTML element displays the human-formatted 1 MiB, but also contains the raw value 1048576. When the user clicks on the element, then the UI might present an option to copy the raw value as well.

Timestamps

Ion directly provides a timestamp type, so whenever a program displays time outputs, WebTerminal can display them intelligently.

For example, a timestamp value like 2022-01-01T18:00:00Z might display as 1 year ago.

<time class="modified-time"
  datetime="2022-01-01T18:00:00Z>
  1 year ago
>

Similarly to file sizes, clicking on the value will allow the user to copy the raw timestamp value to the clipboard.

Customizable Hypermedia Content and Style

Since WebTerminal employs typed and tagged output formats, the standard terminal environment can render stylized output using CSS in ways that are most useful to the user. Additionally, the user might customize their environment by supplying their own CSS style sheets. For example, the user might style the HTML elements described above:

.path {
    color: blue;
    cursor: pointer;
}
.path:hover {
    text-decoration: underline;
}
.size {
  font-weight: bold;
}
.modified-time {
    color: grey;
}