sai 0.1.0

data/lib/sai/support.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require 'sai/terminal/color_mode'
+
+module Sai
+  # Determine the color capabilities of the terminal
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since unreleased
+  #
+  # @api public
+  class Support
+    # Initialize a new instance of Support
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @param color_mode [Integer] the color mode
+    #
+    # @return [Support] the new instance of support
+    # @rbs (Integer color_mode) -> void
+    def initialize(color_mode)
+      @color_mode = color_mode
+    end
+
+    # Check if the terminal supports ANSI colors (4-bit)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check if the terminal supports ANSI colors
+    #   Sai.ansi? # => true
+    #
+    # @return [Boolean] `true` if the terminal supports ANSI colors (4-bit), otherwise `false`
+    # @rbs () -> bool
+    def ansi?
+      @color_mode >= Terminal::ColorMode::ANSI
+    end
+    alias bit4? ansi?
+    alias four_bit? ansi?
+
+    # Check if the terminal supports basic colors (3-bit)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check if the terminal supports basic colors
+    #   Sai.basic? # => true
+    #
+    # @return [Boolean] `true` if the terminal supports basic colors (3-bit), otherwise `false`
+    # @rbs () -> bool
+    def basic?
+      @color_mode >= Terminal::ColorMode::BASIC
+    end
+    alias bit3? basic?
+    alias three_bit? basic?
+
+    # Check if the terminal supports 256 colors (8-bit)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check if the terminal supports 256 colors
+    #   Sai.bit_8? # => true
+    #
+    # @return [Boolean] `true` if the terminal supports 256 colors (8-bit), otherwise `false`
+    # @rbs () -> bool
+    def bit8?
+      @color_mode >= Terminal::ColorMode::BIT8
+    end
+    alias eight_bit? bit8?
+
+    # Check if the terminal supports color output
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check if the terminal supports color
+    #   Sai.color? # => true
+    #
+    # @return [Boolean] `true` if the terminal supports color output, otherwise `false`
+    # @rbs () -> bool
+    def color?
+      @color_mode > Terminal::ColorMode::NO_COLOR
+    end
+
+    # Check if the terminal supports true color (24-bit)
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check if the terminal supports true color
+    #   Sai.true_color? # => true
+    #
+    # @return [Boolean] `true` if the terminal supports true color (24-bit), otherwise `false`
+    # @rbs () -> bool
+    def true_color?
+      @color_mode >= Terminal::ColorMode::TRUE_COLOR
+    end
+    alias bit24? true_color?
+    alias twenty_four_bit? true_color?
+  end
+end

data/lib/sai/terminal/capabilities.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'sai/terminal/color_mode'
+
+module Sai
+  module Terminal
+    # Detect the color capabilities of the terminal
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    module Capabilities
+      class << self
+        # Detect the color capabilities of the current terminal
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @return [Integer] the {ColorMode} of the terminal
+        # @rbs () -> Integer
+        def detect_color_support
+          return ColorMode::NO_COLOR if no_color?
+          return ColorMode::TRUE_COLOR if true_color?
+          return ColorMode::BIT8 if bit8?
+          return ColorMode::ANSI if ansi?
+          return ColorMode::BASIC if basic?
+
+          ColorMode::NO_COLOR
+        end
+
+        private
+
+        # Check for ANSI color support
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @return [Boolean] `true` if the terminal supports basic ANSI colors, otherwise `false`
+        # @rbs () -> bool
+        def ansi?
+          return true if ENV.fetch('TERM', '').match?(/^(xterm|screen|vt100|ansi)/)
+
+          !ENV.fetch('COLORTERM', '').empty?
+        end
+
+        # Check for basic color support
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @return [Boolean] `true` if the terminal supports basic colors, otherwise `false`
+        # @rbs () -> bool
+        def basic?
+          !ENV.fetch('TERM', '').empty?
+        end
+
+        # Check for 256 color (8-bit) support
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @return [Boolean] `true` if the terminal supports 256 colors, otherwise `false`
+        # @rbs () -> bool
+        def bit8?
+          return true if ENV.fetch('TERM', '').end_with?('-256color')
+
+          ENV.fetch('COLORTERM', '0').to_i >= 256
+        end
+
+        # Check for NO_COLOR environment variable
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @see https://no-color.org
+        #
+        # @return [Boolean] `true` if the NO_COLOR environment variable is set, otherwise `false`
+        # @rbs () -> bool
+        def no_color?
+          !ENV.fetch('NO_COLOR', '').empty? || !$stdout.tty?
+        end
+
+        # Check for true color (24-bit) support
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since unreleased
+        #
+        # @api private
+        #
+        # @return [Boolean] `true` if the terminal supports true color, otherwise `false`
+        # @rbs () -> bool
+        def true_color?
+          return true if ENV.fetch('COLORTERM', '').match?(/^(truecolor|24bit)$/)
+
+          case ENV.fetch('TERM', nil)
+          when 'xterm-direct', 'xterm-truecolor'
+            return true
+          end
+
+          case ENV.fetch('TERM_PROGRAM', nil)
+          when 'iTerm.app', 'WezTerm', 'vscode'
+            return true
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/sai/terminal/color_mode.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Sai
+  module Terminal
+    # Represents different color support levels for terminal interfaces
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    module ColorMode
+      # The terminal does not support color output
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @return [Integer] the color mode
+      NO_COLOR = 0 #: Integer
+
+      # The terminal supports 8 colors (3-bit)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @return [Integer] the color mode
+      BASIC = 1 #: Integer
+
+      # The terminal supports 16 colors (4-bit)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @return [Integer] the color mode
+      ANSI = 2 #: Integer
+
+      # The terminal supports 256 colors (8-bit)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @return [Integer] the color mode
+      BIT8 = 3 #: Integer
+
+      # The terminal supports 16 million colors (24-bit)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @return [Integer] the color mode
+      TRUE_COLOR = 4 #: Integer
+    end
+  end
+end

data/lib/sai.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'sai/decorator'
+require 'sai/support'
+require 'sai/terminal/capabilities'
+require 'singleton'
+
+# An elegant color management system for crafting sophisticated CLI applications
+#
+# Sai (彩) - meaning 'coloring' or 'paint' in Japanese - is a powerful and intuitive system for managing color output in
+# command-line applications. Drawing inspiration from traditional Japanese artistic techniques, Sai brings vibrancy and
+# harmony to terminal interfaces through its sophisticated color management
+#
+# Sai empowers developers to create beautiful, colorful CLI applications that maintain visual consistency across
+# different terminal capabilities. Like its artistic namesake, it combines simplicity and sophistication to bring rich,
+# adaptive color to your terminal interfaces
+#
+# When included in a class or module, Sai provides the following instance methods:
+# * {#decorator} - Returns a new instance of {Decorator} for method chaining
+# * {#terminal_color_support} - Returns the color support capabilities of the current terminal
+#
+# The Sai module itself responds to all the same methods as {Decorator}, excluding methods used for applying
+# decorations (apply, call, decorate, encode). These methods are directly delegated to a new {Decorator} instance
+#
+# @author {https://aaronmallen.me Aaron Allen}
+# @since unreleased
+#
+# @api public
+#
+# @example Using Sai as a module
+#   class MyClass
+#     include Sai
+#   end
+#
+#   my_class = MyClass.new
+#   my_class.decorator.red.on_blue.bold.decorate('Hello, World!')
+#   #=> "\e[38;2;205;0;0m\e[48;2;0;0;238m\e[1mHello, World!\e[0m"
+#
+#   my_class.terminal_color_support.true_color? # => true
+#
+# @example Using Sai directly
+#   Sai.red.on_blue.bold.decorate('Hello, World!')
+#   #=> "\e[38;2;205;0;0m\e[48;2;0;0;238m\e[1mHello, World!\e[0m"
+#
+#   Sai.support.true_color? # => true
+module Sai
+  class << self
+    ignored_decorator_methods = %i[apply call decorate encode]
+    Decorator.instance_methods(false).reject { |m| ignored_decorator_methods.include?(m) }.each do |method|
+      define_method(method) do |*arguments, **keyword_arguments|
+        Decorator.new(send(:color_mode)).public_send(method, *arguments, **keyword_arguments)
+      end
+    end
+
+    # @rbs!
+    #   def black: () -> self
+    #   def blink: () -> self
+    #   def blue: () -> self
+    #   def bold: () -> self
+    #   def bright_black: () -> self
+    #   def bright_blue: () -> self
+    #   def bright_cyan: () -> self
+    #   def bright_green: () -> self
+    #   def bright_magenta: () -> self
+    #   def bright_red: () -> self
+    #   def bright_white: () -> self
+    #   def bright_yellow: () -> self
+    #   def conceal: () -> self
+    #   def cyan: () -> self
+    #   def dim: () -> self
+    #   def green: () -> self
+    #   def italic: () -> self
+    #   def magenta: () -> self
+    #   def no_blink: () -> self
+    #   def no_conceal: () -> self
+    #   def no_italic: () -> self
+    #   def no_reverse: () -> self
+    #   def no_strike: () -> self
+    #   def no_underline: () -> self
+    #   def normal_intensity: () -> self
+    #   def on_black: () -> self
+    #   def on_blue: () -> self
+    #   def on_bright_black: () -> self
+    #   def on_bright_blue: () -> self
+    #   def on_bright_cyan: () -> self
+    #   def on_bright_green: () -> self
+    #   def on_bright_magenta: () -> self
+    #   def on_bright_red: () -> self
+    #   def on_bright_white: () -> self
+    #   def on_bright_yellow: () -> self
+    #   def on_cyan: () -> self
+    #   def on_green: () -> self
+    #   def on_magenta: () -> self
+    #   def on_red: () -> self
+    #   def on_white: () -> self
+    #   def on_yellow: () -> self
+    #   def rapid_blink: () -> self
+    #   def red: () -> self
+    #   def reverse: () -> self
+    #   def strike: () -> self
+    #   def underline: () -> self
+    #   def white: () -> self
+    #   def yellow: () -> self
+
+    # The supported color modes for the terminal
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api public
+    #
+    # @example Check the color support of the terminal
+    #   Sai.support.ansi? # => true
+    #   Sai.support.basic? # => true
+    #   Sai.support.bit8? # => true
+    #   Sai.support.no_color? # => false
+    #   Sai.support.true_color? # => true
+    #
+    # @return [Support] the color support
+    # @rbs () -> Support
+    def support
+      @support ||= Support.new(color_mode).freeze
+    end
+
+    private
+
+    # Detect the color capabilities of the terminal
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def color_mode
+      Thread.current[:sai_color_mode] ||= Terminal::Capabilities.detect_color_support
+    end
+  end
+
+  # A helper method to initialize an instance of {Decorator}
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since unreleased
+  #
+  # @api public
+  #
+  # @example Initialize a new instance of {Decorator}
+  #   class MyClass
+  #     include Sai
+  #   end
+  #
+  #   MyClass.new.decorator.blue.on_red.bold.decorate('Hello, world!')
+  #   #=> "\e[38;5;21m\e[48;5;160m\e[1mHello, world!\e[0m"
+  #
+  # @return [Decorator] the Decorator instance
+  # @rbs () -> Decorator
+  def decorator
+    Decorator.new(Terminal::Capabilities.detect_color_support)
+  end
+
+  # The supported color modes for the terminal
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since unreleased
+  #
+  # @api public
+  #
+  # @example Check the color support of the terminal
+  #   class MyClass
+  #     include Sai
+  #   end
+  #
+  #   MyClass.new.terminal_color_support.ansi? # => true
+  #   MyClass.new.terminal_color_support.basic? # => true
+  #   MyClass.new.terminal_color_support.bit8? # => true
+  #   MyClass.new.terminal_color_support.no_color? # => false
+  #   MyClass.new.terminal_color_support.true_color? # => true
+  #
+  # @return [Support] the color support
+  # @rbs () -> Support
+  def terminal_color_support
+    Sai.support
+  end
+end

data/sig/sai/ansi.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/sai/ansi.rb with RBS::Inline
+
+module Sai
+  # ANSI constants for encoding text styles and colors
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since unreleased
+  #
+  # @api private
+  module ANSI
+    # ANSI color code mappings
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Integer}] the color codes
+    COLOR_CODES: untyped
+
+    # Standard ANSI color names and their RGB values
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Array<Integer>}] the color names and RGB values
+    COLOR_NAMES: untyped
+
+    # ANSI escape sequence for resetting text formatting
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [String] the ANSI escape sequence
+    RESET: ::String
+
+    # Standard ANSI style codes
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Integer}] the style codes
+    STYLES: untyped
+  end
+end

data/sig/sai/conversion/color_sequence.rbs

@@ -0,0 +1,114 @@
+# Generated from lib/sai/conversion/color_sequence.rb with RBS::Inline
+
+module Sai
+  module Conversion
+    # ANSI escape sequence utilities
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    module ColorSequence
+      type style_type = :foreground | :background
+
+      # Convert a color to the appropriate ANSI escape sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param color [String, Array<Integer>] the color to convert
+      # @param mode [Integer] the terminal color mode
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [String] the ANSI escape sequence
+      # @rbs (Array[Integer] | String | Symbol color, Integer mode, ?style_type style_type) -> String
+      def self.resolve: (Array[Integer] | String | Symbol color, Integer mode, ?style_type style_type) -> String
+
+      # Convert RGB values to a 4-bit ANSI color sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param rgb [Array<Integer>] the RGB components
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [String] the ANSI escape sequence
+      # @rbs (Array[Integer] rgb, style_type style_type) -> String
+      private def self.ansi: (Array[Integer] rgb, style_type style_type) -> String
+
+      # Convert a base color to a foreground or background sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param base_code [Integer] the base color code
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [Integer] the code for the color sequence
+      # @rbs (Integer base_code, style_type style_type) -> Integer
+      private def self.base_color_for_style_type: (Integer base_code, style_type style_type) -> Integer
+
+      # Convert RGB values to a 3-bit basic color sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param rgb [Array<Integer>] the RGB components
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [String] the ANSI escape sequence
+      # @rbs (Array[Integer] rgb, style_type style_type) -> String
+      private def self.basic: (Array[Integer] rgb, style_type style_type) -> String
+
+      # Convert RGB values to an 8-bit color sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param rgb [Array<Integer>] the RGB components
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [String] the ANSI escape sequence
+      # @rbs (Array[Integer] rgb, style_type type) -> String
+      private def self.bit8: (Array[Integer] rgb, style_type type) -> String
+
+      # Convert RGB values to a true color (24-bit) sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param rgb [Array<Integer>] the RGB components
+      # @param style_type [Symbol] the type of color (foreground or background)
+      #
+      # @return [String] the ANSI escape sequence
+      # @rbs (Array[Integer] rgb, style_type type) -> String
+      private def self.true_color: (Array[Integer] rgb, style_type type) -> String
+
+      # Validate a color style type
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since unreleased
+      #
+      # @api private
+      #
+      # @param style_type [Symbol] the style type to validate
+      #
+      # @raise [ArgumentError] if the style type is invalid
+      # @return [Symbol] the validated style type
+      # @rbs (Symbol style_type) -> Symbol
+      private def self.validate_style_type: (Symbol style_type) -> Symbol
+    end
+  end
+end