Shopify CLI UI

The CLI::UI::Frame module allows you to create visual boundaries in the terminal to organize content. Frames can be nested, creating a hierarchical visual structure where each nested frame inherits or overrides the styling of its parent.

There are two ways to use frames:

1. Block Form (Recommended): You pass a block to CLI::UI::Frame.open. The frame automatically closes when the block finishes. The return value of the block determines if the frame is marked as a success or failure. If the block raises an error, the frame is automatically closed with a failure state.
2. Blockless Form: You call CLI::UI::Frame.open without a block. In this mode, you must manually call CLI::UI::Frame.close to terminate the frame. This mode is strongly discouraged.

When nesting frames, CLI::UI::Frame.divider can be used to add horizontal separators within a frame, and it correctly respects the nesting level to maintain visual alignment.

# Block form with automatic success/failure handling
CLI::UI::Frame.open('Task Name', success_text: 'Done!', failure_text: 'Failed') do
  # Perform work here
  puts 'Working...'
end

# Nested framing
CLI::UI::Frame.open('Parent') do
  puts 'Parent content'
  CLI::UI::Frame.open('Child') do
    puts 'Child content'
    CLI::UI::Frame.divider('Separator')
  end
end

To create a custom UI widget in cli-ui, you must subclass CLI::UI::Widgets::Base. Your implementation must define two specific methods:

1. self.argparse_pattern: Returns a Regexp used to parse the string argument passed to the widget. This pattern is used during initialization to extract named capture groups into instance variables.
2. render: Returns a String representing the visual output of the widget.

When you call WidgetClass.call("argument"), the base class instantiates your widget, parses the argument using your pattern, and calls render. If the argument does not match your pattern, it raises a CLI::UI::Widgets::InvalidWidgetArguments error.

module CLI
  module UI
    module Widgets
      class MyCustomWidget < Base
        def self.argparse_pattern
          /my_pattern/(?<name>\w+)/
        end

        def render
          "Rendered: #{@name}"
        end
      end
    end
  end
end

# Usage:
puts CLI::UI::Widgets::MyCustomWidget.call("some_value")

The InteractiveOptions prompt provides a highly interactive terminal interface for selecting one or more items from a list.

Interaction Modes

• Root Mode: The default state where users navigate the list and select an item.
• Filter Mode: Triggered by f or /. Users type to filter the visible list. Pressing Ctrl-D or Backspace on an empty filter returns to Root mode.
• Line Select Mode: Triggered by e, :, or G (for lists > 9 items). Allows users to type specific line numbers to select items quickly.
• Esc Mode: Handles escape sequences for advanced navigation (e.g., using Page Up/Down via arrow key sequences).

Selection Logic

• Single Selection: The call method returns the string value of the selected option.
• Multiple Selection: When multiple: true is enabled, the prompt displays checkboxes (☐/☑). Users toggle items and must select the Done option to return the array of selected strings.