sai 0.1.0

checksums.yaml

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

data/.yardopts

@@ -0,0 +1,11 @@
+lib/**/*.rb
+--title Sai
+--readme README.md
+--no-private
+--protected
+--markup markdown
+--markup-provider redcarpet
+--embed-mixins
+--tag rbs
+--hide-tag rbs
+--files LICENSE

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog], and this project adheres to [Break Versioning].
+
+## [Unreleased]
+
+## 0.1.0 - 2025-01-19
+
+* Initial release
+
+[Keep a Changelog]: https://keepachangelog.com/en/1.0.0/
+[Break Versioning]: https://www.taoensso.com/break-versioning
+
+<!-- versions -->
+
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.1.0..HEAD

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Aaron Allen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,275 @@
+# Sai
+
+[![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 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
+
+```ruby
+puts Sai.rgb(255, 128, 0).bold.decorate('Create beautiful CLI applications')
+puts Sai.hex('#4834d4').italic.decorate('with intuitive color management')
+puts Sai.bright_cyan.on_blue.underline.decorate('that adapts to any terminal')
+```
+
+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.
+
+## Features
+
+* Automatic color mode detection and downgrading
+* Support for True Color (24-bit), 256 colors (8-bit), ANSI colors (4-bit), and basic colors (3-bit)
+* Rich set of ANSI text styles
+* Named color support with bright variants
+* RGB and Hex color support
+* Foreground and background colors
+* Respects NO_COLOR environment variable
+* Can be used directly or included in classes/modules
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'sai'
+```
+
+Or install it yourself as:
+
+```bash
+gem install sai
+```
+
+## Usage
+
+Sai can be used directly or included in your own classes and modules.
+
+### Direct Usage
+
+```ruby
+require 'sai'
+
+# Using named colors
+puts Sai.red.decorate('Error!')
+puts Sai.bright_blue.on_white.decorate('Info')
+
+# Using RGB colors
+puts Sai.rgb(255, 128, 0).decorate('Custom color')
+puts Sai.on_rgb(0, 255, 128).decorate('Custom background')
+
+# Using hex colors
+puts Sai.hex('#FF8000').decorate('Hex color')
+puts Sai.on_hex('#00FF80').decorate('Hex background')
+
+# Applying styles
+puts Sai.bold.underline.decorate('Important')
+puts Sai.red.bold.italic.decorate('Error!')
+
+# Complex combinations
+puts Sai.bright_cyan
+       .on_blue
+       .bold
+       .italic
+       .decorate('Styled text')
+```
+
+### Module Inclusion
+
+```ruby
+class CLI
+  include Sai
+
+  def error(message)
+    puts decorator.red.bold.decorate(message)
+  end
+
+  def info(message)
+    puts decorator.bright_blue.decorate(message)
+  end
+
+  def success(message)
+    puts decorator.green.decorate(message)
+  end
+end
+
+cli = CLI.new
+cli.error('Something went wrong!')
+cli.info('Processing...')
+cli.success('Done!')
+```
+
+### Defining Reusable Styles
+
+Sai decorators can be assigned to constants to create reusable styles throughout your application:
+
+```ruby
+module Style
+  ERROR = Sai.bold.bright_white.on_red
+  WARNING = Sai.black.on_yellow
+  SUCCESS = Sai.bright_green
+  INFO = Sai.bright_blue
+  HEADER = Sai.bold.bright_cyan.underline
+end
+
+# Use your defined styles
+puts Style::ERROR.decorate('Something went wrong!')
+puts Style::SUCCESS.decorate('Operation completed successfully')
+
+# Styles can be further customized when needed
+puts Style::ERROR.italic.decorate('Critical error!')
+```
+
+> [!TIP]
+> This pattern is particularly useful for maintaining consistent styling across your application and creating theme
+> systems. You can even build on existing styles:
+>
+> ```ruby
+> module Theme
+>   PRIMARY = Sai.rgb(63, 81, 181)
+>   SECONDARY = Sai.rgb(255, 87, 34)
+>
+>   BUTTON = PRIMARY.bold
+>   LINK = SECONDARY.underline
+>   HEADER = PRIMARY.bold.underline
+> end
+> ```
+
+## Features
+
+### Color Support
+
+Sai supports up to 16.7 million colors (true color/24-bit) depending on your terminal's capabilities. Colors can be
+specified in several ways:
+
+#### RGB Colors
+
+```ruby
+# Specify any RGB color (0-255 per channel)
+Sai.rgb(255, 128, 0).decorate('Orange text')
+Sai.on_rgb(0, 255, 128).decorate('Custom green background')
+```
+
+#### Hex Colors
+
+```ruby
+# Use any hex color code
+Sai.hex('#FF8000').decorate('Orange text')
+Sai.on_hex('#00FF80').decorate('Custom green background')
+```
+
+#### Named Color Shortcuts
+
+For convenience, Sai provides shortcuts for common ANSI colors:
+
+Standard colors:
+
+```ruby
+Sai.red.decorate('Red text')
+Sai.blue.decorate('Blue text')
+Sai.on_green.decorate('Green background')
+```
+
+Bright variants:
+
+```ruby
+Sai.bright_red.decorate('Bright red text')
+Sai.bright_blue.decorate('Bright blue text')
+Sai.on_bright_green.decorate('Bright green background')
+```
+
+Available named colors:
+
+* black/bright_black
+* red/bright_red
+* green/bright_green
+* yellow/bright_yellow
+* blue/bright_blue
+* magenta/bright_magenta
+* cyan/bright_cyan
+* white/bright_white
+
+> [!TIP]
+> While named colors provide convenient shortcuts, remember that Sai supports the full RGB color space. Don't feel
+> limited to just these predefined colors!
+
+### Text Styles
+
+Available styles:
+
+* bold
+* dim
+* italic
+* underline
+* blink
+* rapid_blink
+* reverse
+* conceal
+* strike
+
+Style removal:
+
+* no_blink
+* no_italic
+* no_underline
+* no_reverse
+* no_conceal
+* no_strike
+* normal_intensity
+
+### Color Mode Detection & Downgrading
+
+Sai automatically detects your terminal's color capabilities and adapts the output appropriately:
+
+* True Color terminals (24-bit): Full access to all 16.7 million colors
+* 256-color terminals (8-bit): Colors are mapped to the closest available color in the 256-color palette
+* ANSI terminals (4-bit): Colors are mapped to the 16 standard ANSI colors
+* Basic terminals (3-bit): Colors are mapped to the 8 basic ANSI colors
+* NO_COLOR: All color sequences are stripped when the NO_COLOR environment variable is set
+
+> [!NOTE]
+> This automatic downgrading ensures your application looks great across all terminal types without any extra code!
+
+### Terminal Support Detection
+
+You can check the terminal's capabilities:
+
+```ruby
+# Using directly
+Sai.support.true_color? # => true/false
+Sai.support.bit8?      # => true/false
+Sai.support.ansi?      # => true/false
+Sai.support.basic?     # => true/false
+Sai.support.color?     # => true/false
+
+# Using included module
+class CLI
+  include Sai
+
+  def check_support
+    if terminal_color_support.true_color?
+      puts "Terminal supports true color!"
+    end
+  end
+end
+```
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](docs/CONTRIBUTING.md) for:
+
+* Development setup and workflow
+* Code style and documentation standards
+* Testing requirements
+* Pull request process
+
+Before contributing, please review our [Code of Conduct](docs/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/sai/ansi.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+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 = {
+      black: 0,
+      red: 1,
+      green: 2,
+      yellow: 3,
+      blue: 4,
+      magenta: 5,
+      cyan: 6,
+      white: 7
+    }.freeze # Hash[Symbol, Integer]
+
+    # 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 = {
+      black: [0, 0, 0],
+      red: [205, 0, 0],
+      green: [0, 205, 0],
+      yellow: [205, 205, 0],
+      blue: [0, 0, 238],
+      magenta: [205, 0, 205],
+      cyan: [0, 205, 205],
+      white: [229, 229, 229],
+      bright_black: [127, 127, 127],
+      bright_red: [255, 0, 0],
+      bright_green: [0, 255, 0],
+      bright_yellow: [255, 255, 0],
+      bright_blue: [92, 92, 255],
+      bright_magenta: [255, 0, 255],
+      bright_cyan: [0, 255, 255],
+      bright_white: [255, 255, 255]
+    }.freeze # Hash[Symbol, Array[Integer]]
+
+    # ANSI escape sequence for resetting text formatting
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [String] the ANSI escape sequence
+    RESET = "\e[0m" # String
+
+    # Standard ANSI style codes
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Integer}] the style codes
+    STYLES = {
+      bold: 1,
+      dim: 2,
+      italic: 3,
+      underline: 4,
+      blink: 5,
+      rapid_blink: 6,
+      reverse: 7,
+      conceal: 8,
+      strike: 9,
+      normal_intensity: 22,
+      no_italic: 23,
+      no_underline: 24,
+      no_blink: 25,
+      no_reverse: 27,
+      no_conceal: 28,
+      no_strike: 29
+    }.freeze # Hash[Symbol, Integer]
+  end
+end

data/lib/sai/conversion/color_sequence.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'sai/ansi'
+require 'sai/conversion/rgb'
+require 'sai/terminal/color_mode'
+
+module Sai
+  module Conversion
+    # ANSI escape sequence utilities
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since unreleased
+    #
+    # @api private
+    module ColorSequence
+      # @rbs!
+      #   type style_type = :foreground | :background
+
+      class << self
+        # 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 resolve(color, mode, style_type = :foreground)
+          rgb = RGB.resolve(color)
+          style_type = validate_style_type(style_type) #: style_type
+
+          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::ANSI then ansi(rgb, style_type)
+          when Terminal::ColorMode::BASIC then basic(rgb, style_type)
+          else
+            ''
+          end
+        end
+
+        private
+
+        # 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
+        def ansi(rgb, style_type)
+          r, g, b = rgb.map { |c| c / 255.0 } #: [Float, Float, Float]
+          brightness = (r + g + b) / 3.0
+          is_bright = brightness > 0.5
+
+          color = RGB.closest_ansi_color(r, g, b)
+          code = base_color_for_style_type(ANSI::COLOR_CODES[color], style_type)
+          code += 60 if is_bright
+          "\e[#{code}m"
+        end
+
+        # 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
+        def base_color_for_style_type(base_code, style_type)
+          style_type == :background ? base_code + 40 : base_code + 30
+        end
+
+        # 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
+        def basic(rgb, style_type)
+          r, g, b = rgb.map { |c| c / 255.0 } #: [Float, Float, Float]
+          color = RGB.closest_ansi_color(r, g, b)
+          code = base_color_for_style_type(ANSI::COLOR_CODES[color], style_type)
+          "\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
+        #
+        # @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 true_color(rgb, style_type)
+          code = style_type == :background ? 48 : 38
+          "\e[#{code};2;#{rgb.join(';')}m"
+        end
+
+        # 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
+        def validate_style_type(style_type)
+          raise ArgumentError, "Invalid style type: #{style_type}" unless %i[foreground background].include?(style_type)
+
+          style_type
+        end
+      end
+    end
+  end
+end