hiiro 0.1.352 → 0.1.353

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16ba8062d4d8f261771beb98b5baad695b43d05f6f0be4f8ebcc0f8e18a6e89b
-  data.tar.gz: b756598368c4faa85ec332df703e4f2e859f84bcdf2c68319dc1b5ce48c6d7ab
+  metadata.gz: bbd7598e65b8521905ec67a960f09700d7260c5329e066e6cfcbb4661c180c99
+  data.tar.gz: 189ca275fa4cc2af210c1d67c8976bc4b90343e68eb4a0fe86ebedea1421bb9f
 SHA512:
-  metadata.gz: 417c7bc005bbe71d9fc62a9cab04616c78005aad16f9604eb98f5aee6cfbe42a19bbbf789f04fb0a452c3ebea7e323155a7432d380f03f6b42cb0be3d4b66260
-  data.tar.gz: 2b0b553966be3f3cfd4d457afa62b7c8021b9633d5eaa92ded65ad808d41256de9216ab495c474fcbad27c3a479f3ff530ad69fe4c6f91457d06f4db213946b6
+  metadata.gz: 50b6f3d077471531303d04f9ef234ff4ade40dbea85b52f575e6c9e3c48088ba1318dd0798eaeef15acdeb4ce0ca8fcf13100d4963fb5174dccdefaf87de228f
+  data.tar.gz: 4c852f5cea47667811dd2dd461b5c1bdfe3935cc7fecad2c95c7d3d43f28d3c7aea0554ea415cfda812e776b047bf4dee9ef77b34fdb0ffc5b806170864e2705

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.1.353] - 2026-04-26
+
+### Added
+- `Hiiro::Tui::ListScreen` for building keyboard-driven full-screen list interfaces
+- `Hiiro::Config.load_yaml` and `Hiiro::Config.yaml_dig` helpers for YAML file loading with nested key access
+
 ## [0.1.352] - 2026-04-24
 
 ### Added
@@ -323,4 +329,4 @@
 - `h db cleanup` subcommand to preview and prune duplicate rows from SQLite tables
 
 ### Fixed
-- Prevent duplicate pinned_prs during import with `insert_conflict` and per-row rescue
+- Prevent duplicate pinned_prs during import with `insert_conflict` and per-row rescue

data/README.md

@@ -8,6 +8,7 @@ A lightweight, extensible CLI framework for Ruby. Build your own multi-command t
 - **Abbreviation matching** - Type `h ex hel` instead of `h example hello`
 - **Plugin system** - Extend functionality with reusable modules
 - **Per-command storage** - Each command gets its own pin/config namespace
+- **TUI helpers** - Build keyboard-driven list screens with `Hiiro::Tui::ListScreen`
 
 See [docs/](docs/) for detailed documentation on all subcommands.
 
@@ -154,6 +155,10 @@ h example hello  # => Hi!
 h example bye    # => Goodbye!
 ```
 
+### Building TUIs
+
+Use `Hiiro::Tui::ListScreen` for simple full-screen list interfaces. Subclass it, override `header_lines`, `format_row`, and `handle_key`, then run it from a normal `Hiiro.run` subcommand.
+
 ### Method 2: Inline Subcommands
 
 Modify `exe/h` directly to add subcommands to the base `h` command:

data/lib/hiiro/config.rb

@@ -1,3 +1,5 @@
+require 'yaml'
+
 class Hiiro
   class Config
     BASE_DIR = File.join(Dir.home, '.config/hiiro')
@@ -15,6 +17,36 @@ class Hiiro
         File.join(BASE_DIR, relpath)
       end
 
+      def load_yaml(relpath = 'config.yml', default: {}, permitted_classes: [Symbol])
+        file = path(relpath)
+        return default unless File.exist?(file)
+
+        YAML.safe_load_file(file, permitted_classes: permitted_classes) || default
+      rescue StandardError
+        default
+      end
+
+      def yaml_dig(relpath = 'config.yml', *keys, default: nil, permitted_classes: [Symbol])
+        value = load_yaml(relpath, default: {}, permitted_classes: permitted_classes)
+
+        keys.flatten.each do |key|
+          return default unless value.is_a?(Hash)
+
+          value =
+            if value.key?(key)
+              value[key]
+            elsif value.key?(key.to_s)
+              value[key.to_s]
+            elsif key.respond_to?(:to_sym) && value.key?(key.to_sym)
+              value[key.to_sym]
+            else
+              return default
+            end
+        end
+
+        value.nil? ? default : value
+      end
+
       def data_path(relpath='')
         File.join(DATA_DIR, relpath)
       end

data/lib/hiiro/tui.rb

@@ -0,0 +1,216 @@
+require 'io/console'
+
+class Hiiro
+  module Tui
+    module Terminal
+      def with_screen
+        input = $stdin
+        $stdout.write("\e[?1049h\e[?25l")
+        $stdout.flush
+
+        input.raw do
+          yield input
+        end
+      ensure
+        $stdout.write("\r\e[0m\e[?25h\e[?1049l")
+        $stdout.flush
+      end
+
+      def read_key(input)
+        char = input.getch
+        return :ctrl_c if char == "\u0003"
+        return :enter if char == "\r" || char == "\n"
+
+        if char == "\e"
+          first = read_escape_char(input)
+          return :escape if first.nil?
+          return :escape unless first == '['
+
+          case read_escape_char(input)
+          when 'A' then :up
+          when 'B' then :down
+          when 'C' then :right
+          when 'D' then :left
+          else :escape
+          end
+        else
+          char
+        end
+      end
+
+      def read_escape_char(input)
+        return nil unless IO.select([input], nil, nil, 0.02)
+
+        input.getch
+      end
+
+      def terminal_rows
+        env_dimension('LINES') || IO.console.winsize[0]
+      rescue StandardError
+        24
+      end
+
+      def terminal_cols
+        env_dimension('COLUMNS') || IO.console.winsize[1]
+      rescue StandardError
+        80
+      end
+
+      def terminal_line(text, cols)
+        truncate(text, cols) + "\e[K"
+      end
+
+      def center_text(text, cols)
+        truncated = truncate(text, cols)
+        return truncated if truncated.length >= cols
+
+        left_padding = [(cols - truncated.length) / 2, 0].max
+        (' ' * left_padding) + truncated
+      end
+
+      def truncate(text, cols)
+        return text if text.length <= cols
+        return text[0, cols] if cols <= 1
+
+        text[0, cols - 1] + '…'
+      end
+
+      def visible_text(text, cols, offset = 0)
+        return truncate(text, cols) if offset <= 0
+
+        clipped = text[offset..] || ''
+        return truncate(clipped, cols) if cols <= 1
+
+        truncate("«#{clipped}", cols)
+      end
+
+      def env_dimension(name)
+        value = ENV[name].to_i
+        return nil unless value.positive?
+
+        value
+      end
+    end
+
+    class ListScreen
+      include Terminal
+
+      attr_reader :items, :cursor, :top, :horizontal_offset
+
+      def initialize(items:, empty_message: 'No items.')
+        @items = items
+        @empty_message = empty_message
+        @cursor = 0
+        @top = 0
+        @horizontal_offset = 0
+      end
+
+      def run
+        if items.empty?
+          puts @empty_message
+          return false
+        end
+
+        with_screen do |input|
+          loop do
+            render
+
+            result = handle_key(read_key(input))
+            return result unless result == :continue
+          end
+        end
+      end
+
+      def handle_key(key)
+        case key
+        when :up, 'k'
+          move(-1)
+        when :down, 'j'
+          move(1)
+        when :left, 'h'
+          scroll_horizontal(-4)
+        when :right, 'l'
+          scroll_horizontal(4)
+        when 'q', :escape, :ctrl_c
+          return false
+        end
+
+        :continue
+      end
+
+      def render
+        rows = terminal_rows
+        cols = terminal_cols
+        line_cols = [cols - 1, 1].max
+        headers = header_lines
+        visible_rows = [rows - headers.length - footer_height, 1].max
+        visible = items[@top, visible_rows] || []
+        @horizontal_offset = [horizontal_offset, max_horizontal_offset(line_cols, visible)].min
+
+        lines = headers.map { |line| terminal_line(line, line_cols) }
+        visible.each_with_index do |item, idx|
+          lines << format_row(item, @top + idx == cursor, line_cols)
+        end
+
+        (visible_rows - visible.length).times { lines << terminal_line('', line_cols) }
+        footer_lines.each { |line| lines << terminal_line(line, line_cols) }
+
+        $stdout.write("\e[H\e[2J")
+        $stdout.write(lines.join("\r\n"))
+        $stdout.write("\r")
+        $stdout.flush
+      end
+
+      def header_lines
+        []
+      end
+
+      def footer_lines
+        ["Showing #{@top + 1}-#{@top + visible_items.length} of #{items.length}"]
+      end
+
+      def footer_height
+        1
+      end
+
+      def format_row(item, current, line_cols)
+        prefix = current ? '> ' : '  '
+        style = current ? "\e[7m" : "\e[0m"
+        text = (prefix + visible_text(item.to_s, [line_cols - prefix.length, 1].max, horizontal_offset)).ljust(line_cols)
+
+        "#{style}#{text}\e[0m\e[K"
+      end
+
+      def move(delta)
+        @cursor = [[cursor + delta, 0].max, items.length - 1].min
+        visible_rows = body_rows_budget
+        @top = cursor if cursor < top
+        @top = cursor - visible_rows + 1 if cursor >= top + visible_rows
+        @horizontal_offset = [horizontal_offset, max_horizontal_offset].min
+      end
+
+      def scroll_horizontal(delta)
+        @horizontal_offset = [[horizontal_offset + delta, 0].max, max_horizontal_offset].min
+      end
+
+      def visible_items
+        items[top, body_rows_budget] || []
+      end
+
+      def body_rows_budget
+        [terminal_rows - header_lines.length - footer_height, 1].max
+      end
+
+      def max_horizontal_offset(line_cols = nil, visible = nil)
+        line_cols ||= [terminal_cols - 1, 1].max
+        visible ||= visible_items
+        return 0 if visible.empty?
+
+        longest_visible_item = visible.map { |item| item.to_s.length }.max || 0
+        min_visible_chars = [5, line_cols].min
+
+        [longest_visible_item - min_visible_chars, 0].max
+      end
+    end
+  end
+end

data/lib/hiiro/version.rb

@@ -1,3 +1,3 @@
 class Hiiro
-  VERSION = "0.1.352"
+  VERSION = "0.1.353"
 end

data/lib/hiiro.rb

@@ -47,6 +47,7 @@ require_relative "hiiro/pane_home"
 require_relative "hiiro/pin_record"
 require_relative "hiiro/reminder"
 require_relative 'hiiro/registry'
+require_relative 'hiiro/tui'
 
 class String
   def underscore(camel_cased_word=self)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hiiro
 version: !ruby/object:Gem::Version
-  version: 0.1.352
+  version: 0.1.353
 platform: ruby
 authors:
 - Joshua Toyota
@@ -377,6 +377,7 @@ files:
 - lib/hiiro/tmux/window.rb
 - lib/hiiro/tmux/windows.rb
 - lib/hiiro/todo.rb
+- lib/hiiro/tui.rb
 - lib/hiiro/version.rb
 - notes
 - obsidian_slides.md