Shore

https://hexdocs.pm/shore
Admin
Shore is a TUI (terminal user interface) framework for Gleam, following The Elm Architecture and...
Tokens:4,347
Snippets:44
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Gleam Shore Application Entry Point Example

Source: https://hexdocs.pm/shore/shore

Illustrates a basic `shore` application setup in Gleam, demonstrating how to initialize the application with `shore.spec`, start it, and handle the exit subject to keep the application running until termination.

```Gleam
import gleam/erlang/process
import shore

pub fn main() {
  let exit = process.new_subject()
  let assert Ok(_actor) =
    shore.spec(
      init:,
      update:,
      view:,
      exit:,
      keybinds: shore.default_keybinds(),
      redraw: shore.on_timer(16),
    )
    |> shore.start
  exit |> process.receive_forever
}
```

--------------------------------

### Gleam Shore Counter TUI Application Example

Source: https://hexdocs.pm/shore/index

This Gleam code provides a complete example of a Shore-based Terminal User Interface (TUI) application. It implements the Elm Architecture pattern with `init`, `update`, and `view` functions to manage a simple counter, demonstrating UI components, event handling, and process management for a responsive terminal experience.

```Gleam
import gleam/erlang/process
import gleam/int
import gleam/option.{Some}
import shore
import shore/key
import shore/layout
import shore/style
import shore/ui

// MAIN

pub fn main() {
  let exit = process.new_subject()
  let assert Ok(_actor) =
    shore.spec(
      init:,
      update:,
      view:,
      exit:,
      keybinds: shore.default_keybinds(),
      redraw: shore.on_timer(16),
    )
    |> shore.start
  exit |> process.receive_forever
}

// MODEL

pub opaque type Model {
  Model(counter: Int)
}

fn init() -> #(Model, List(fn() -> Msg)) {
  let model = Model(counter: 0)
  let cmds = []
  #(model, cmds)
}

// UPDATE

pub opaque type Msg {
  Increment
  Decrement
}

fn update(model: Model, msg: Msg) -> #(Model, List(fn() -> Msg)) {
  case msg {
    Increment -> #(Model(counter: model.counter + 1), [])
    Decrement -> #(Model(counter: model.counter - 1), [])
  }
}

// VIEW

fn view(model: Model) -> shore.Node(Msg) {
  ui.box(
    [
      ui.text(
        "keybinds

i: increments
d: decrements
ctrl+x: exits
      ",
      ),
      ui.text(int.to_string(model.counter)),
      ui.br(),
      ui.row([
        ui.button("increment", key.Char("i"), Increment),
        ui.button("decrement", key.Char("d"), Decrement),
      ]),
    ],
    Some("counter"),
  )
  |> ui.align(style.Center, _)
  |> layout.center(style.Px(50), style.Px(12))
}
```

--------------------------------

### Install Shore TUI Framework in Gleam Project

Source: https://hexdocs.pm/shore/index

This command adds the `shore` library as a dependency to a Gleam project, specifying version 1. It's the first step to integrate Shore for building terminal user interfaces.

```Shell
gleam add shore@1
```

--------------------------------

### Key Type Constructors Reference

Source: https://hexdocs.pm/shore/shore/key

Provides a reference to the available constructors (variants) for the `Key` opaque type. These constructors are used to create instances of the `Key` type, representing specific keyboard events or character inputs.

```APIDOC
Type: Key
  Constructors:
    - Backspace
    - Enter
    - Left
    - Right
    - Up
    - Down
    - Home
    - End
    - PageUp
    - PageDown
    - Tab
    - BackTab
    - Delete
    - Insert
    - F(Int)
    - Char(String)
    - Null
    - Esc
    - Ctrl(String)
```

--------------------------------

### APIDOC: shore.start Function

Source: https://hexdocs.pm/shore/shore

Initiates the `shore` application actor based on the provided `Spec` and returns a subject that can be used to send events to the running application.

```Gleam
pub fn start(
  spec: @internal Spec(model, msg),
) -> Result(
  process.Subject(@internal Event(msg)),
  actor.StartError,
)
```

--------------------------------

### Create a Cell for Grid Placement

Source: https://hexdocs.pm/shore/shore/layout

The `cell` function constructs a `Cell` instance, specifying its content and its precise position within a `Grid` using row and column spans. This allows for flexible content placement and sizing within grid layouts.

```Gleam
pub fn cell(
  content content: @internal Node(msg),
  row row: #(Int, Int),
  col col: #(Int, Int),
) -> @internal Cell(msg)
```

```APIDOC
cell(
  content: @internal Node(msg),
  row: #(Int, Int),
  col: #(Int, Int)
) -> @internal Cell(msg)
```

--------------------------------

### API: table_kv function (Gleam)

Source: https://hexdocs.pm/shore/shore/ui

This function creates a Key-Value style table layout, useful for displaying pairs of information. It takes a `width` for the table and a `List(List(String))` where each inner list is expected to contain a key and a value. The output is an `@internal Node(msg)` representing the UI component.

```APIDOC
pub fn table_kv(
  width: style.Size,
  table: List(List(String)),
) -> @internal Node(msg)
```

--------------------------------

### Gleam `br` function

Source: https://hexdocs.pm/shore/shore/ui

Creates an empty line.

```Gleam
pub fn br() -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.spec Function

Source: https://hexdocs.pm/shore/shore

Defines the core components of a `shore` application, following The Elm Architecture. It requires `init`, `view`, and `update` functions, an exit subject, keybindings, and a redraw strategy. The `init` and `update` functions support effectful operations via a list of functions, which are handled in a separate Erlang process.

```Gleam
pub fn spec(
  init init: fn() -> #(model, List(fn() -> msg)),
  view view: fn(model) -> @internal Node(msg),
  update update: fn(model, msg) -> #(model, List(fn() -> msg)),
  exit exit: process.Subject(Nil),
  keybinds keybinds: @internal Keybinds,
  redraw redraw: @internal Redraw,
) -> @internal Spec(model, msg)
```

--------------------------------

### Convert String to Key Type in Gleam

Source: https://hexdocs.pm/shore/shore/key

Defines the `from_string` function, a utility that converts a string representation of a key (e.g., "ctrl+c", "enter") into its corresponding `Key` type. This function is essential for parsing key inputs from configuration files, command-line arguments, or other string-based sources.

```Gleam
pub fn from_string(key: String) -> Key
```

--------------------------------

### API: text_styled function (Gleam)

Source: https://hexdocs.pm/shore/shore/ui

This function creates a text string UI node with customizable foreground and background colors. It accepts the `text` content as a `String` and optional `fg` (foreground) and `bg` (background) colors as `option.Option(style.Color)`. The result is an `@internal Node(msg)` representing the styled text element.

```APIDOC
pub fn text_styled(
  text: String,
  fg: option.Option(style.Color),
  bg: option.Option(style.Color),
) -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.default_keybinds Function

Source: https://hexdocs.pm/shore/shore

Returns a typical set of default keybindings for common TUI actions, including application exit, submitting input, and navigating focus between UI elements.

```Gleam
pub fn default_keybinds() -> @internal Keybinds
```

--------------------------------

### Create a 50/50 Split Layout

Source: https://hexdocs.pm/shore/shore/layout

The `split` function generates a simple layout that divides the available space into two equal halves. It's ideal for presenting two distinct content areas side-by-side, such as a left panel and a right panel.

```Gleam
pub fn split(
  left: @internal Node(msg),
  right: @internal Node(msg),
) -> @internal Node(msg)
```

```APIDOC
split(
  left: @internal Node(msg),
  right: @internal Node(msg)
) -> @internal Node(msg)
```

--------------------------------

### Gleam `progress` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a progress bar that automatically calculates fill percentage based on maximum and current values.

```Gleam
pub fn progress(
  width: style.Size,
  max: Int,
  value: Int,
  color: style.Color,
) -> @internal Node(msg)
```

--------------------------------

### Gleam `debug` function

Source: https://hexdocs.pm/shore/shore/ui

Prints some positional information for developer debugging purposes.

```Gleam
pub fn debug() -> @internal Node(msg)
```

--------------------------------

### Gleam `button` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a button assigned to a key press to execute an event.

```Gleam
pub fn button(
  text: String,
  key: key.Key,
  event: msg,
) -> @internal Node(msg)
```

--------------------------------

### Gleam `input` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a field for text input.

```Gleam
pub fn input(
  label: String,
  value: String,
  width: style.Size,
  event: fn(String) -> msg,
) -> @internal Node(msg)
```

--------------------------------

### API: table function (Gleam)

Source: https://hexdocs.pm/shore/shore/ui

This function generates a standard table layout for UI display. It requires a specified `width` for the table and a `List(List(String))` representing the table's content. The function returns an `@internal Node(msg)` which is a UI element.

```APIDOC
pub fn table(
  width: style.Size,
  table: List(List(String)),
) -> @internal Node(msg)
```

--------------------------------

### Gleam `graph` function

Source: https://hexdocs.pm/shore/shore/ui

Creates an extremely simple plot based on provided points.

```Gleam
pub fn graph(
  width: style.Size,
  height: style.Size,
  points: List(Float),
) -> @internal Node(msg)
```

--------------------------------

### API: text function (Gleam)

Source: https://hexdocs.pm/shore/shore/ui

This function generates a basic UI node containing a simple text string. It takes a single `String` argument which is the content to be displayed. The function returns an `@internal Node(msg)` that can be integrated into the UI.

```APIDOC
pub fn text(text: String) -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.keybinds Function

Source: https://hexdocs.pm/shore/shore

Allows setting custom keybindings for various `shore` framework-level functions. This includes actions like moving between focusable elements (input boxes, buttons), exiting the application, and triggering button events.

```Gleam
pub fn keybinds(
  exit exit: key.Key,
  submit submit: key.Key,
  focus_clear focus_clear: key.Key,
  focus_next focus_next: key.Key,
  focus_prev focus_prev: key.Key,
) -> @internal Keybinds
```

--------------------------------

### Gleam `bar` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a row with a background color.

```Gleam
pub fn bar(color: style.Color) -> @internal Node(msg)
```

--------------------------------

### Center Content Layout

Source: https://hexdocs.pm/shore/shore/layout

The `center` function provides a convenient layout for centering content both vertically and horizontally. It takes the content node and desired width and height, returning a new node with the content centered within those dimensions.

```Gleam
pub fn center(
  content: @internal Node(msg),
  width: style.Size,
  height: style.Size,
) -> @internal Node(msg)
```

```APIDOC
center(
  content: @internal Node(msg),
  width: style.Size,
  height: style.Size
) -> @internal Node(msg)
```

--------------------------------

### Gleam `bar2` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a row with a background color, containing specified items.

```Gleam
pub fn bar2(
  color: style.Color,
  node: @internal Node(msg),
) -> @internal Node(msg)
```

--------------------------------

### Gleam `box` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a box container element for holding other nodes.

```Gleam
pub fn box(
  children: List(@internal Node(msg)),
  title: option.Option(String),
) -> @internal Node(msg)
```

--------------------------------

### Define a Grid-Based Layout

Source: https://hexdocs.pm/shore/shore/layout

The `grid` function creates a flexible grid layout, similar to CSS Grid. It allows defining row and column sizes, specifying gaps between cells, and populating the grid with `Cell` instances. This is a powerful tool for structuring complex UI elements.

```Gleam
pub fn grid(
  gap gap: Int,
  rows rows: List(style.Size),
  cols cols: List(style.Size),
  cells cells: List(@internal Cell(msg)),
) -> @internal Node(msg)
```

```APIDOC
grid(
  gap: Int,
  rows: List(style.Size),
  cols: List(style.Size),
  cells: List(@internal Cell(msg))
) -> @internal Node(msg)
```

--------------------------------

### Gleam `keybind` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a non-visible button assigned to a key press to execute an event.

```Gleam
pub fn keybind(key: key.Key, event: msg) -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.on_timer Function

Source: https://hexdocs.pm/shore/shore

Specifies that the TUI should redraw itself every `x` milliseconds. This is useful for applications requiring periodic updates or animations.

```Gleam
pub fn on_timer(ms ms: Int) -> @internal Redraw
```

--------------------------------

### Gleam `hr` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a horizontal line.

```Gleam
pub fn hr() -> @internal Node(msg)
```

--------------------------------

### Define Gleam `Size` Type for UI Element Dimensions

Source: https://hexdocs.pm/shore/shore/style

Defines the `Size` type in Gleam, providing flexible options for configuring the dimensions of UI elements. It supports absolute pixel values (`Px(Int)`), percentages of the parent's size (`Pct(Int)`), and a `Fill` option to automatically occupy available space. The `Fill` constructor intelligently divides space among multiple items within a layout. An API documentation view is also provided.

```Gleam
pub type Size {
  Px(Int)
  Pct(Int)
  Fill
}
```

```APIDOC
type Size:
  Configurable size options/units for ui elements
  Constructors:
    Px(Int): Absolute width/height
    Pct(Int): A percentage of the parent item width/height
    Fill: Will fit the item to the parents width/height. When multiple exist within a single item, such as a layout, will automatically divide the space between items.
```

--------------------------------

### APIDOC: shore.on_update Function

Source: https://hexdocs.pm/shore/shore

Specifies that the TUI should redraw only in response to events. This redraw strategy is suitable for applications where the state changes infrequently.

```Gleam
pub fn on_update() -> @internal Redraw
```

--------------------------------

### Gleam `col` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a container element for holding other nodes over multiple lines, arranging them vertically.

```Gleam
pub fn col(
  children: List(@internal Node(msg)),
) -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.Node Type Definition

Source: https://hexdocs.pm/shore/shore

Represents a UI element or component within the `shore` TUI framework, used to define the visual structure of the terminal interface.

```Gleam
pub type Node(msg) =
  @internal Node(msg)
```

--------------------------------

### Gleam `hr_styled` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a colored horizontal line.

```Gleam
pub fn hr_styled(color: style.Color) -> @internal Node(msg)
```

--------------------------------

### Define Key Type for Keyboard Input in Gleam

Source: https://hexdocs.pm/shore/shore/key

Defines the `Key` opaque type, an enumeration representing various keyboard inputs such as special keys (Backspace, Enter, F-keys), character inputs, and control combinations. This type is fundamental for handling user input in terminal applications built with Gleam.

```Gleam
pub type Key {
  Backspace
  Enter
  Left
  Right
  Up
  Down
  Home
  End
  PageUp
  PageDown
  Tab
  BackTab
  Delete
  Insert
  F(Int)
  Char(String)
  Null
  Esc
  Ctrl(String)
}
```

--------------------------------

### Gleam `align` function

Source: https://hexdocs.pm/shore/shore/ui

Sets alignment of all child nodes.

```Gleam
pub fn align(
  alignment: style.Align,
  node: @internal Node(msg),
) -> @internal Node(msg)
```

--------------------------------

### Gleam `row` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a container element for holding other nodes in a single line, arranging them horizontally.

```Gleam
pub fn row(
  children: List(@internal Node(msg)),
) -> @internal Node(msg)
```

--------------------------------

### APIDOC: shore.exit Function

Source: https://hexdocs.pm/shore/shore

Manually triggers the exit event for your TUI application. This function provides a programmatic way to terminate the TUI, complementing the configured exit keybind.

```Gleam
pub fn exit() -> @internal Event(msg)
```

--------------------------------

### Define and Use the Cell Type

Source: https://hexdocs.pm/shore/shore/layout

The `Cell` type is a fundamental building block within the `shore` layout system, representing an item placed inside a `Grid`. It's an internal type parameterized by a message type `msg`.

```Gleam
pub type Cell(msg) =
  @internal Cell(msg)
```

```APIDOC
Cell(msg):
  Type: @internal Cell(msg)
```

--------------------------------

### APIDOC: shore.send Function

Source: https://hexdocs.pm/shore/shore

Enables sending a message to your TUI from another actor or process. This allows external events to push updates to your TUI, rather than requiring it to poll for changes.

```Gleam
pub fn send(msg: msg) -> @internal Event(msg)
```

--------------------------------

### APIDOC: shore.Event Type Definition

Source: https://hexdocs.pm/shore/shore

Defines the `Event` type used to send messages within the `shore` TUI framework. Events are typically sent using the `send` function to trigger updates.

```Gleam
pub type Event(msg) =
  @internal Event(msg)
```

--------------------------------

### Gleam `input_hidden` function

Source: https://hexdocs.pm/shore/shore/ui

Creates a field for text input with the content display hidden, useful for password fields.

```Gleam
pub fn input_hidden(
  label: String,
  value: String,
  width: style.Size,
  event: fn(String) -> msg,
) -> @internal Node(msg)
```

--------------------------------

### Define Gleam `Align` Type for UI Alignment

Source: https://hexdocs.pm/shore/shore/style

Defines the `Align` type in Gleam, a sum type used to specify horizontal alignment for UI elements. It provides `Left`, `Center`, and `Right` constructors, allowing developers to control the positioning of children within an `Aligned` component. This entry also includes a structured API documentation view of the type.

```Gleam
pub type Align {
  Left
  Center
  Right
}
```

```APIDOC
type Align:
  Used to set all children of `Aligned` to the selected alignment.
  Constructors:
    Left
    Center
    Right
```

--------------------------------

### Define Gleam `Color` Type for ANSI Terminal Colors

Source: https://hexdocs.pm/shore/shore/style

Defines the `Color` type in Gleam, an enumeration representing standard ANSI terminal colors. This type is primarily used for setting the background and foreground colors of UI elements, enhancing visual presentation. It includes common color constructors such as `Black`, `Red`, `Green`, `Yellow`, `Blue`, `Magenta`, `Cyan`, and `White`. An API documentation view is also provided.

```Gleam
pub type Color {
  Black
  Red
  Green
  Yellow
  Blue
  Magenta
  Cyan
  White
}
```

```APIDOC
type Color:
  ANSI terminal color. Used for setting the background/foreground of UI elements.
  Constructors:
    Black
    Red
    Green
    Yellow
    Blue
    Magenta
    Cyan
    White
```
Tokens:
Raw