sai 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d27e2e0d0202e3dc41887be8cfa58f3d862fdee0c9fc3dbd0db792bac1d8f91
-  data.tar.gz: c1a6cd0918fd89b72fe1bd22479192354293a270803297fe901df818032fbfb5
+  metadata.gz: 0c45105e60b5f7a3a93d837080975996e96a340aef0ad3fd86cd4b5a1be17e8f
+  data.tar.gz: baf93c18ef40221c86c329deeeaabbe7a3619744d3a80a9349314624a4af3995
 SHA512:
-  metadata.gz: 958aae38da9095a09347a97dd5eddca62a2ac2b4f2eddf51ee4e5b11f4ffdeed26918dad6f00bd85129f82de8eafbde5eb1ed6e3c6a8136d6d5ad6cf3b3765fe
-  data.tar.gz: cce26cf788ae60731b58cf2460cea923bda925db36a75f009ec4846046edf47afbd10a81990c7651a0cde21d1090c725dbc7b5e290f412968b83c0dc5f61e1db
+  metadata.gz: c1540fe3fd55f0a338ff04ff6f9794e831b831c040637f4cdd4f0de0ab0a689a55f95d5c1a744f3ae25b0bc7452983044568e83b6e665439672142cd2abd811b
+  data.tar.gz: 4244b0401b7fd0af26665a0a5b5622dd09bd364e4166bc8d12a6c69f94a52b09511d56afe2cd8eaedf1401c402b3ba63845aa900c147e408312221dcc243e21d

data/.yardopts

@@ -8,4 +8,4 @@ lib/**/*.rb
 --embed-mixins
 --tag rbs
 --hide-tag rbs
---files LICENSE
+--files LICENSE,docs/USAGE.md

data/CHANGELOG.md

@@ -6,6 +6,41 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 ## [Unreleased]
 
+## [0.3.1] - 2025-01-22
+
+### Added 
+
+* [#8](https://github.com/aaronmallen/sai/pull/8) - Add color manipulation methods for darkening and lightening colors 
+  by [@aaronmallen](https://github.com/aaronmallen)
+* [#9](https://github.com/aaronmallen/sai/pull/9) - Add gradient and rainbow color effects for text and backgrounds by
+  [@aaronmallen](https://github.com/aaronmallen)
+* [#13](https://github.com/aaronmallen/sai/pull/13) - Add support for over 360 named colors expanding the color palette
+  by [@aaronmallen](https://github.com/aaronmallen)
+
+### Changed
+
+* [#10](https://github.com/aaronmallen/sai/pull/10) - Refactor `Sai::Decorator` into component modules by
+  [@aaronmallen](https://github.com/aaronmallen)
+* [#11](https://github.com/aaronmallen/sai/pull/11) - Refactor `Sai::Conversion::RGB` into component modules by
+  [@aaronmallen](https://github.com/aaronmallen)
+* [#12](https://github.com/aaronmallen/sai/pull/12) - Refactor ANSI sequence processing into specialized parser classes
+  by [@aaronmallen](https://github.com/aaronmallen)
+
+## [0.3.0] - 2025-01-20
+
+### Added
+
+* [#6](https://github.com/aaronmallen/sai/pull/6) - Add `Sai::ANSI::SequencedString` for ANSI string manipulation by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+### Changed
+
+* [#5](https://github.com/aaronmallen/sai/pull/5) - Remove unnecessary error handling in `Sai::Decorator` by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+* [#6](https://github.com/aaronmallen/sai/pull/6) - Changed `Sai::Decorator#decorate` now returns a
+  `Sai::ANSI::SequencedString` by [@aaronmallen](https://github.com/aaronmallen)
+
 ## [0.2.0] - 2025-01-20
 
 ### Added
@@ -29,5 +64,7 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 <!-- versions -->
 
-[Unreleased]: https://github.com/aaronmallen/sai/compare/0.2.0..HEAD
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.3.1..HEAD
+[0.3.1]: https://github.com/aaronmallen/sai/compare/0.3.0..0.3.1
+[0.3.0]: https://github.com/aaronmallen/sai/compare/0.2.0..0.3.0
 [0.2.0]: https://github.com/aaronmallen/sai/compare/0.1.0..0.2.0

data/README.md

@@ -1,36 +1,43 @@
 # 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 Codacy grade](https://img.shields.io/codacy/grade/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai)
+[![Sai Codacy coverage](https://img.shields.io/codacy/coverage/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai/coverage)
 [![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.2.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.3.1)
 [![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')
+# Create beautiful CLI applications with intuitive color management
+puts Sai.rgb(255, 128, 0).bold.decorate('Warning: Battery Low')
+puts Sai.hex('#4834d4').italic.decorate('Processing request...')
+puts Sai.bright_cyan.on_blue.underline.decorate('Download Complete!')
+
+# Adjust color brightness
+puts Sai.red.darken_text(0.3).decorate('Subtle Error Message')
+puts Sai.blue.lighten_text(0.5).decorate('Highlighted Info')
+
+# Analyze and manipulate ANSI-encoded text
+text = Sai.sequence("\e[31mError:\e[0m Connection failed")
+puts text.without_color  # Keep formatting, remove colors
+puts text.stripped      # Get plain text without any formatting
 ```
 
 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
+* Rich color support (True Color, 256 colors, ANSI, and basic modes)
+* Automatic terminal capability detection and color mode adaptation
+* RGB, Hex, and named color (**over 360 named colors**) support with bright variants
+* Comprehensive text styling (bold, italic, underline, etc.)
+* Advanced ANSI sequence parsing and manipulation
+* Intelligent color downgrading for compatibility
 * Respects NO_COLOR environment variable
-* Can be used directly or included in classes/modules
 
 ## Installation
 
@@ -42,20 +49,20 @@ gem 'sai'
 
 Or install it yourself as:
 
-```bash
+```ruby
 gem install sai
 ```
 
-## Usage
-
-Sai can be used directly or included in your own classes and modules.
+> [!IMPORTANT]  
+> If you're upgrading from version 0.2.0, please see our [Migration Guide](docs/migrations/0.2.0-0.3.0.md) for
+> important changes.
 
-### Direct Usage
+## Quick Start
 
 ```ruby
 require 'sai'
 
-# Using named colors
+# Basic usage
 puts Sai.red.decorate('Error!')
 puts Sai.bright_blue.on_white.decorate('Info')
 
@@ -63,234 +70,25 @@ puts Sai.bright_blue.on_white.decorate('Info')
 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')
+# Color manipulation
+puts Sai.blue.lighten_text(0.5).decorate('Lightened blue')
+puts Sai.red.darken_text(0.3).decorate('Darkened red')
 
 # 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.with_mode(color_mode.ansi_auto).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!
-
-### 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')
+# Working with ANSI sequences
+text = Sai.sequence("\e[31mError:\e[0m Details here")
+puts text.without_color    # Remove colors but keep formatting
+puts text.without_style    # Remove formatting but keep colors
+puts text.stripped        # Get plain text
 ```
 
-> [!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`).
+## Documentation
 
-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:
-
-```ruby
-# Using directly
-Sai.support.true_color? # => true/false
-Sai.support.advanced?   # => 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
-```
+* [Complete Usage Guide](docs/USAGE.md) - Comprehensive documentation of all features
+* [API Documentation](https://rubydoc.info/gems/sai/0.3.1) - Detailed API reference
 
 ## Contributing