sai 0.1.0 → 0.2.0

data/lib/sai.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
+require 'sai/conversion/color_sequence'
+require 'sai/conversion/rgb'
 require 'sai/decorator'
+require 'sai/mode_selector'
 require 'sai/support'
 require 'sai/terminal/capabilities'
-require 'singleton'
+require 'sai/terminal/color_mode'
 
 # An elegant color management system for crafting sophisticated CLI applications
 #
@@ -23,7 +26,7 @@ require 'singleton'
 # decorations (apply, call, decorate, encode). These methods are directly delegated to a new {Decorator} instance
 #
 # @author {https://aaronmallen.me Aaron Allen}
-# @since unreleased
+# @since 0.1.0
 #
 # @api public
 #
@@ -48,100 +51,121 @@ module Sai
     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)
+        Decorator.new(mode: Sai.mode.auto).public_send(method, *arguments, **keyword_arguments)
       end
     end
 
+    # The Sai {ModeSelector mode selector}
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.auto #=> 4
+    #
+    # @return [ModeSelector] the mode selector
+    # @rbs () -> singleton(ModeSelector)
+    def mode
+      ModeSelector
+    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
+    #   def black: () -> Decorator
+    #   def blink: () -> Decorator
+    #   def blue: () -> Decorator
+    #   def bold: () -> Decorator
+    #   def bright_black: () -> Decorator
+    #   def bright_blue: () -> Decorator
+    #   def bright_cyan: () -> Decorator
+    #   def bright_green: () -> Decorator
+    #   def bright_magenta: () -> Decorator
+    #   def bright_red: () -> Decorator
+    #   def bright_white: () -> Decorator
+    #   def bright_yellow: () -> Decorator
+    #   def conceal: () -> Decorator
+    #   def cyan: () -> Decorator
+    #   def dim: () -> Decorator
+    #   def green: () -> Decorator
+    #   def italic: () -> Decorator
+    #   def magenta: () -> Decorator
+    #   def no_blink: () -> Decorator
+    #   def no_conceal: () -> Decorator
+    #   def no_italic: () -> Decorator
+    #   def no_reverse: () -> Decorator
+    #   def no_strike: () -> Decorator
+    #   def no_underline: () -> Decorator
+    #   def normal_intensity: () -> Decorator
+    #   def on_black: () -> Decorator
+    #   def on_blue: () -> Decorator
+    #   def on_bright_black: () -> Decorator
+    #   def on_bright_blue: () -> Decorator
+    #   def on_bright_cyan: () -> Decorator
+    #   def on_bright_green: () -> Decorator
+    #   def on_bright_magenta: () -> Decorator
+    #   def on_bright_red: () -> Decorator
+    #   def on_bright_white: () -> Decorator
+    #   def on_bright_yellow: () -> Decorator
+    #   def on_cyan: () -> Decorator
+    #   def on_green: () -> Decorator
+    #   def on_magenta: () -> Decorator
+    #   def on_red: () -> Decorator
+    #   def on_white: () -> Decorator
+    #   def on_yellow: () -> Decorator
+    #   def rapid_blink: () -> Decorator
+    #   def red: () -> Decorator
+    #   def reverse: () -> Decorator
+    #   def strike: () -> Decorator
+    #   def underline: () -> Decorator
+    #   def white: () -> Decorator
+    #   def yellow: () -> Decorator
 
     # The supported color modes for the terminal
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api public
     #
     # @example Check the color support of the terminal
     #   Sai.support.ansi? # => true
     #   Sai.support.basic? # => true
-    #   Sai.support.bit8? # => true
+    #   Sai.support.advanced? # => true
     #   Sai.support.no_color? # => false
     #   Sai.support.true_color? # => true
     #
     # @return [Support] the color support
-    # @rbs () -> Support
+    # @rbs () -> singleton(Support)
     def support
-      @support ||= Support.new(color_mode).freeze
+      Support
     end
+  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
+  # A helper method that provides Sai color modes
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  # @example
+  #   class MyClass
+  #     include Sai
+  #   end
+  #
+  #   MyClass.new.color_mode.ansi #=> 2
+  #
+  # @return [ModeSelector] the mode selector
+  # @rbs () -> singleton(ModeSelector)
+  def color_mode
+    ModeSelector
   end
 
   # A helper method to initialize an instance of {Decorator}
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -153,16 +177,21 @@ module Sai
   #   MyClass.new.decorator.blue.on_red.bold.decorate('Hello, world!')
   #   #=> "\e[38;5;21m\e[48;5;160m\e[1mHello, world!\e[0m"
   #
+  #   MyClass.new.decorator(mode: Sai.mode.no_color)
+  #   #=> "Hello, world!"
+  #
+  # @param mode [Integer] the color mode to use
+  #
   # @return [Decorator] the Decorator instance
-  # @rbs () -> Decorator
-  def decorator
-    Decorator.new(Terminal::Capabilities.detect_color_support)
+  # @rbs (?mode: Integer) -> Decorator
+  def decorator(mode: Sai.mode.auto)
+    Decorator.new(mode:)
   end
 
   # The supported color modes for the terminal
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -173,13 +202,13 @@ module Sai
   #
   #   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.advanced? # => true
   #   MyClass.new.terminal_color_support.no_color? # => false
   #   MyClass.new.terminal_color_support.true_color? # => true
   #
   # @return [Support] the color support
-  # @rbs () -> Support
+  # @rbs () -> singleton(Support)
   def terminal_color_support
-    Sai.support
+    Support
   end
 end

data/sig/sai/ansi.rbs

@@ -4,14 +4,14 @@ module Sai
   # ANSI constants for encoding text styles and colors
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api private
   module ANSI
     # ANSI color code mappings
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
@@ -21,7 +21,7 @@ module Sai
     # Standard ANSI color names and their RGB values
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
@@ -31,7 +31,7 @@ module Sai
     # ANSI escape sequence for resetting text formatting
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
@@ -41,7 +41,7 @@ module Sai
     # Standard ANSI style codes
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #

data/sig/sai/conversion/color_sequence.rbs

@@ -5,7 +5,7 @@ module Sai
     # ANSI escape sequence utilities
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module ColorSequence
@@ -14,7 +14,7 @@ module Sai
       # Convert a color to the appropriate ANSI escape sequence
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -26,10 +26,24 @@ module Sai
       # @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 an 8-bit color sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      #
+      # @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.advanced: (Array[Integer] rgb, style_type type) -> String
+
       # Convert RGB values to a 4-bit ANSI color sequence
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -43,7 +57,7 @@ module Sai
       # Convert a base color to a foreground or background sequence
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -57,7 +71,7 @@ module Sai
       # Convert RGB values to a 3-bit basic color sequence
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -68,24 +82,10 @@ module Sai
       # @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
+      # @since 0.1.0
       #
       # @api private
       #
@@ -99,7 +99,7 @@ module Sai
       # Validate a color style type
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #

data/sig/sai/conversion/rgb.rbs

@@ -5,14 +5,14 @@ module Sai
     # RGB color conversion utilities
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module RGB
       # Get closest ANSI color for RGB values
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -27,7 +27,7 @@ module Sai
       # Determine if a color is dark
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -42,7 +42,7 @@ module Sai
       # Determine if a color is grayscale
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -57,7 +57,7 @@ module Sai
       # Convert a color value to RGB components
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -71,7 +71,7 @@ module Sai
       # Convert RGB values to 256-color cube index
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -84,7 +84,7 @@ module Sai
       # Convert RGB values to grayscale index
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -97,7 +97,7 @@ module Sai
       # Check if RGB values represent cyan
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -112,7 +112,7 @@ module Sai
       # Convert a hex string to RGB values
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -125,7 +125,7 @@ module Sai
       # Check if RGB values represent magenta
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -140,7 +140,7 @@ module Sai
       # Convert a named color to RGB values
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -154,7 +154,7 @@ module Sai
       # Determine if RGB values represent a primary color
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -169,7 +169,7 @@ module Sai
       # Get the closest primary color
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -184,7 +184,7 @@ module Sai
       # Determine if RGB values represent a secondary color
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -199,7 +199,7 @@ module Sai
       # Get the closest secondary color
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -214,7 +214,7 @@ module Sai
       # Validate RGB values
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -227,7 +227,7 @@ module Sai
       # Check if RGB values represent yellow
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #