sai 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1856d33db7e7b71a3ad164df38fc64a732e806540584e5e207ed6ee6220d0e07
-  data.tar.gz: f2aa1b1182b297dcdd14c97b01928e33b56e2bee79268e3f344ea4df315a338f
+  metadata.gz: 0d27e2e0d0202e3dc41887be8cfa58f3d862fdee0c9fc3dbd0db792bac1d8f91
+  data.tar.gz: c1a6cd0918fd89b72fe1bd22479192354293a270803297fe901df818032fbfb5
 SHA512:
-  metadata.gz: 318ead79460d995f10d20a031d8d9be16277bd5180d5663f32ba7a0f1aac3dbdfa5f7e7fba6c71c62662cbf9486db35b7cb95e6562ff3df9860cd837f2ca9125
-  data.tar.gz: a82a2ce509d1d6159cbac457d788e48bf88bb07498449beffedbf1fb10aa08a2e614c375f0af3207a22b4b6b32fe0b595137e6b36276f011e11489a786ec51af
+  metadata.gz: 958aae38da9095a09347a97dd5eddca62a2ac2b4f2eddf51ee4e5b11f4ffdeed26918dad6f00bd85129f82de8eafbde5eb1ed6e3c6a8136d6d5ad6cf3b3765fe
+  data.tar.gz: cce26cf788ae60731b58cf2460cea923bda925db36a75f009ec4846046edf47afbd10a81990c7651a0cde21d1090c725dbc7b5e290f412968b83c0dc5f61e1db

data/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-20
+
+### Added
+
+* [#3](https://github.com/aaronmallen/sai/pull/3) - mode selection via `Sai::ModeSelector`by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+### Changed
+
+* [#2](https://github.com/aaronmallen/sai/pull/2) - Immutable method chaining for `Sai::Decorator` by
+  [@aaronmallen](https://github.com/aaronmallen)
+* [#3](https://github.com/aaronmallen/sai/pull/3) - `Sia::Support` from class to module for improved API design by
+  [@aaronmallen](https://github.com/aaronmallen)
+
 ## 0.1.0 - 2025-01-19
 
 * Initial release
@@ -15,4 +29,5 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 <!-- versions -->
 
-[Unreleased]: https://github.com/aaronmallen/sai/compare/0.1.0..HEAD
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.2.0..HEAD
+[0.2.0]: https://github.com/aaronmallen/sai/compare/0.1.0..0.2.0

data/README.md

@@ -2,7 +2,7 @@
 
 [![Sai Version](https://img.shields.io/gem/v/sai?style=for-the-badge&logo=rubygems&logoColor=white&logoSize=auto&label=Gem%20Version)](https://rubygems.org/gems/sai)
 [![Sai License](https://img.shields.io/github/license/aaronmallen/sai?style=for-the-badge&logo=opensourceinitiative&logoColor=white&logoSize=auto)](./LICENSE)
-[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.1.0)
+[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.2.0)
 [![Sai Open Issues](https://img.shields.io/github/issues-search/aaronmallen/sai?query=state%3Aopen&style=for-the-badge&logo=github&logoColor=white&logoSize=auto&label=issues&color=red)](https://github.com/aaronmallen/sai/issues?q=state%3Aopen%20)
 
 An elegant color management system for crafting sophisticated CLI applications
@@ -73,10 +73,10 @@ puts Sai.red.bold.italic.decorate('Error!')
 
 # Complex combinations
 puts Sai.bright_cyan
-       .on_blue
-       .bold
-       .italic
-       .decorate('Styled text')
+        .on_blue
+        .bold
+        .italic
+        .decorate('Styled text')
 ```
 
 ### Module Inclusion
@@ -94,7 +94,7 @@ class CLI
   end
 
   def success(message)
-    puts decorator.green.decorate(message)
+    puts decorator.with_mode(color_mode.ansi_auto).green.decorate(message)
   end
 end
 
@@ -235,6 +235,39 @@ Sai automatically detects your terminal's color capabilities and adapts the outp
 > [!NOTE]
 > This automatic downgrading ensures your application looks great across all terminal types without any extra code!
 
+### Color Mode Selection
+
+Sai provides flexible color mode selection through its `mode` interface:
+
+```ruby
+# Use automatic mode detection (default)
+Sai.with_mode(Sai.mode.auto)
+
+# Force specific color modes
+puts Sai.with_mode(Sai.mode.true_color).red.decorate('24-bit color')
+puts Sai.with_mode(Sai.mode.advanced).red.decorate('256 colors')
+puts Sai.with_mode(Sai.mode.ansi).red.decorate('16 colors')
+puts Sai.with_mode(Sai.mode.basic).red.decorate('8 colors')
+puts Sai.with_mode(Sai.mode.no_color).red.decorate('No color')
+
+# Use automatic downgrading
+puts Sai.with_mode(Sai.mode.advanced_auto).red.decorate('256 colors or less')
+puts Sai.with_mode(Sai.mode.ansi_auto).red.decorate('16 colors or less')
+puts Sai.with_mode(Sai.mode.basic_auto).red.decorate('8 colors or less')
+```
+
+> [!WARNING]
+> When using fixed color modes (like `true_color` or `advanced`), Sai will not automatically downgrade colors for
+> terminals with lower color support. For automatic color mode adjustment, use modes ending in `_auto`
+> (like `advanced_auto` or `ansi_auto`).
+
+This allows you to:
+
+* Explicitly set specific color modes
+* Use automatic mode detection (default)
+* Set maximum color modes with automatic downgrading
+* Disable colors entirely
+
 ### Terminal Support Detection
 
 You can check the terminal's capabilities:
@@ -242,7 +275,7 @@ You can check the terminal's capabilities:
 ```ruby
 # Using directly
 Sai.support.true_color? # => true/false
-Sai.support.bit8?      # => true/false
+Sai.support.advanced?   # => true/false
 Sai.support.ansi?      # => true/false
 Sai.support.basic?     # => true/false
 Sai.support.color?     # => true/false

data/lib/sai/ansi.rb

@@ -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
     #
@@ -30,7 +30,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
     #
@@ -57,7 +57,7 @@ module Sai
     # ANSI escape sequence for resetting text formatting
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
@@ -67,7 +67,7 @@ module Sai
     # Standard ANSI style codes
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #

data/lib/sai/conversion/color_sequence.rb

@@ -9,7 +9,7 @@ module Sai
     # ANSI escape sequence utilities
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module ColorSequence
@@ -20,7 +20,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
         #
@@ -36,7 +36,7 @@ module Sai
 
           case mode
           when Terminal::ColorMode::TRUE_COLOR then true_color(rgb, style_type)
-          when Terminal::ColorMode::BIT8 then bit8(rgb, style_type)
+          when Terminal::ColorMode::ADVANCED then advanced(rgb, style_type)
           when Terminal::ColorMode::ANSI then ansi(rgb, style_type)
           when Terminal::ColorMode::BASIC then basic(rgb, style_type)
           else
@@ -46,10 +46,33 @@ module Sai
 
         private
 
+        # 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
+        def advanced(rgb, style_type)
+          code = style_type == :background ? 48 : 38
+          color_code = if rgb.uniq.size == 1
+                         RGB.to_grayscale_index(rgb)
+                       else
+                         RGB.to_color_cube_index(rgb)
+                       end
+
+          "\e[#{code};5;#{color_code}m"
+        end
+
         # Convert RGB values to a 4-bit ANSI color sequence
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -72,7 +95,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
         #
@@ -88,7 +111,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
         #
@@ -104,33 +127,10 @@ module Sai
           "\e[#{code}m"
         end
 
-        # 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
-        def bit8(rgb, style_type)
-          code = style_type == :background ? 48 : 38
-          color_code = if rgb.uniq.size == 1
-                         RGB.to_grayscale_index(rgb)
-                       else
-                         RGB.to_color_cube_index(rgb)
-                       end
-
-          "\e[#{code};5;#{color_code}m"
-        end
-
         # Convert RGB values to a true color (24-bit) sequence
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -147,7 +147,7 @@ module Sai
         # Validate a color style type
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #

data/lib/sai/conversion/rgb.rb

@@ -7,7 +7,7 @@ module Sai
     # RGB color conversion utilities
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module RGB
@@ -15,7 +15,7 @@ module Sai
         # Get closest ANSI color for RGB values
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -37,7 +37,7 @@ module Sai
         # Determine if a color is dark
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -54,7 +54,7 @@ module Sai
         # Determine if a color is grayscale
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -71,7 +71,7 @@ module Sai
         # Convert a color value to RGB components
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -96,7 +96,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
         #
@@ -112,7 +112,7 @@ module Sai
         # Convert RGB values to grayscale index
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -129,7 +129,7 @@ module Sai
         # Check if RGB values represent cyan
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -146,7 +146,7 @@ module Sai
         # Convert a hex string to RGB values
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -166,7 +166,7 @@ module Sai
         # Check if RGB values represent magenta
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -183,7 +183,7 @@ module Sai
         # Convert a named color to RGB values
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -201,7 +201,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
         #
@@ -220,7 +220,7 @@ module Sai
         # Get the closest primary color
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -242,7 +242,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
         #
@@ -263,7 +263,7 @@ module Sai
         # Get the closest secondary color
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -284,7 +284,7 @@ module Sai
         # Validate RGB values
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #
@@ -303,7 +303,7 @@ module Sai
         # Check if RGB values represent yellow
         #
         # @author {https://aaronmallen.me Aaron Allen}
-        # @since unreleased
+        # @since 0.1.0
         #
         # @api private
         #