sai 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c45105e60b5f7a3a93d837080975996e96a340aef0ad3fd86cd4b5a1be17e8f
-  data.tar.gz: baf93c18ef40221c86c329deeeaabbe7a3619744d3a80a9349314624a4af3995
+  metadata.gz: 70b2bd4d6b105fd634f0685c9e7952f061881b6c150abb1193c268bc11daee06
+  data.tar.gz: 7c39b485b0a6217326c7b282d88518114348c8dd1bef3ddfaea7d697f314ccb7
 SHA512:
-  metadata.gz: c1540fe3fd55f0a338ff04ff6f9794e831b831c040637f4cdd4f0de0ab0a689a55f95d5c1a744f3ae25b0bc7452983044568e83b6e665439672142cd2abd811b
-  data.tar.gz: 4244b0401b7fd0af26665a0a5b5622dd09bd364e4166bc8d12a6c69f94a52b09511d56afe2cd8eaedf1401c402b3ba63845aa900c147e408312221dcc243e21d
+  metadata.gz: 105164ddad126c7996f5f1ebe4e32baf0f881b7672731b922f71025712a6d2ea95a276fe27e4660ad8e3b26e5cbcdbf6f5d4179138846f5b07093cb68e0b929b
+  data.tar.gz: 11763b7688478e3068bf389b15eecea0b63ea768a7d5031c98e3df1b76c96fbb5d9b317a7fcf0f10f0473cc20f1e9a24104a96c03f4f1aa07273359c1fde865d

data/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 ## [Unreleased]
 
+## [0.4.0] - 2025-01-23
+
+### Changed
+
+* [#17](https://github.com/aaronmallen/sai/pull/17) - Refactor color registration and delegation system by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+## [0.3.2] - 2025-01-22
+
+### Added
+
+* [#15](https://github.com/aaronmallen/sai/pull/15) - Add support for registering custom named colors by
+  [@aaronmallen](https://github.com/aaronmallen)
+
 ## [0.3.1] - 2025-01-22
 
 ### Added 
@@ -64,7 +78,9 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 <!-- versions -->
 
-[Unreleased]: https://github.com/aaronmallen/sai/compare/0.3.1..HEAD
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.4.0..HEAD
+[0.4.0]: https://github.com/aaronmallen/sai/compare/0.3.2..0.4.0
+[0.3.2]: https://github.com/aaronmallen/sai/compare/0.3.1..0.3.2
 [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

@@ -4,7 +4,7 @@
 [![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.3.1)
+[![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.4.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
@@ -33,12 +33,33 @@ harmony to terminal interfaces through its sophisticated color management.
 
 * 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
+* RGB, Hex, and named color 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
 
+## Extended Color Palettes
+
+Looking for additional color palettes? Check out [Sai-Mei](https://github.com/aaronmallen/sai-mei), which extends Sai
+with many curated color collections, including:
+
+* Web colors from CSS Color Module Level 4
+* Tailwind CSS color system
+* Extended 256-color xterm palette
+
+```ruby
+# Install Sai-Mei alongside Sai
+gem 'sai'
+gem 'sai-mei'
+
+# Then use sophisticated color palettes
+require 'sai/mei'
+Sai::Mei.css.install      # CSS colors
+Sai::Mei.tailwind.install # Tailwind colors
+Sai::Mei.xterm.install    # Terminal 256 colors
+```
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -54,7 +75,7 @@ gem install sai
 ```
 
 > [!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
+> If you're upgrading from version 0.3.1, please see our [Migration Guide](docs/migrations/0.3.1-0.4.0.md) for
 > important changes.
 
 ## Quick Start
@@ -88,7 +109,7 @@ puts text.stripped        # Get plain text
 ## Documentation
 
 * [Complete Usage Guide](docs/USAGE.md) - Comprehensive documentation of all features
-* [API Documentation](https://rubydoc.info/gems/sai/0.3.1) - Detailed API reference
+* [API Documentation](https://rubydoc.info/gems/sai/0.4.0) - Detailed API reference
 
 ## Contributing
 

data/docs/USAGE.md

@@ -84,28 +84,35 @@ Sai.bright_red.decorate('Bright red text')
 Sai.bright_blue.decorate('Bright blue text')
 Sai.on_bright_green.decorate('Bright green background')
 ```
-### Named Colors
-
-Common ANSI, XTERM, and CSS colors have convenient shortcuts. You can:
 
-```ruby
-# View all available colors programmatically
-Sai::NamedColors.names  # Returns array of all color names
+Available named colors:
 
-# Use colors in your code
-Sai.red.decorate('Red text')
-Sai.blue.decorate('Blue text')
-Sai.on_green.decorate('Green background')
-```
+* 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!
 
-For a complete list of available colors, see:
+#### Registering Custom Named Colors
+
+Sai allows you to register custom named colors for easy reuse with `Sai.register`:
+
+```ruby
+# Register custom colors
+Sai.register(:my_color, '#CF4C5F')
+
+# or alternatively 
+Sai.register(:my_color, [207, 76, 95])
 
-* [Online Color Reference](https://github.com/aaronmallen/sai/blob/main/docs/AVAILABLE_NAMED_COLORS.md)
-* `Sai::NamedColors.names` in your code
+Sai.my_color.decorate('Hello, world!')
+```
 
 ### Color Manipulation
 

data/lib/sai/ansi.rb

@@ -8,6 +8,33 @@ module Sai
   #
   # @api private
   module ANSI
+    # Standard ANSI color names and their RGB values
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.1
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Array<Integer>}] the color names and RGB values
+    COLORS = {
+      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 color code mappings
     #
     # @author {https://aaronmallen.me Aaron Allen}
@@ -63,5 +90,18 @@ module Sai
       no_conceal: 28,
       no_strike: 29
     }.freeze # Hash[Symbol, Integer]
+
+    # Install the ANSI colors
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.4.0
+    #
+    # @api private
+    #
+    # @return [void]
+    # @rbs () -> void
+    def self.install
+      COLORS.each_pair { |name, color| Sai.register(name, color) }
+    end
   end
 end

data/lib/sai/conversion/rgb/color_space.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'sai/named_colors'
+require 'sai/registry'
 
 module Sai
   module Conversion
@@ -120,7 +120,7 @@ module Sai
           # @return [Array<Integer>] the RGB components
           # @rbs (String color_name) -> Array[Integer]
           def named_to_rgb(color_name)
-            color = NamedColors[color_name.to_sym]
+            color = Registry[color_name.to_sym]
             raise ArgumentError, "Unknown color name: #{color_name}" unless color
 
             color

data/lib/sai/decorator/delegator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'sai/decorator/color_manipulations'
+require 'sai/decorator/gradients'
+require 'sai/decorator/hex_colors'
+require 'sai/decorator/named_styles'
+require 'sai/decorator/rgb_colors'
+
+module Sai
+  class Decorator
+    # Provides method delegation to the {Decorator} class for classes or modules that include it
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.4.0
+    #
+    # @abstract Include in a class or module to provide method delegation to the {Decorator} class
+    # @api private
+    module Delegator
+      # @rbs!
+      #   def blink: () -> Decorator
+      #   def bold: () -> Decorator
+      #   def conceal: () -> Decorator
+      #   def darken_background: () -> Decorator
+      #   def darken_bg: () -> Decorator
+      #   def darken_fg: () -> Decorator
+      #   def darken_foreground: () -> Decorator
+      #   def darken_text: () -> Decorator
+      #   def dim: () -> Decorator
+      #   def gradient: () -> Decorator
+      #   def hex: () -> Decorator
+      #   def italic: () -> Decorator
+      #   def lighten_background: () -> Decorator
+      #   def lighten_bg: () -> Decorator
+      #   def lighten_fg: () -> Decorator
+      #   def lighten_foreground: () -> Decorator
+      #   def lighten_text: () -> 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_gradient: () -> Decorator
+      #   def on_hex: () -> Decorator
+      #   def on_rainbow: () -> Decorator
+      #   def on_rgb: () -> Decorator
+      #   def rainbow: () -> Decorator
+      #   def rapid_blink: () -> Decorator
+      #   def reverse: () -> Decorator
+      #   def rgb: () -> Decorator
+      #   def strike: () -> Decorator
+      #   def underline: () -> Decorator
+
+      [ColorManipulations, Gradients, HexColors, NamedStyles, RGBColors].each do |mod|
+        mod.instance_methods.each do |method|
+          define_method(method) do |*arguments, **keyword_arguments|
+            Decorator.new.public_send(method, *arguments, **keyword_arguments)
+          end
+        end
+      end
+
+      # Apply a specific color mode to the {Decorator} instance
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.4.0
+      #
+      # @api private
+      #
+      # @param mode [Integer] the color mode to use
+      #
+      # @return [Decorator] a new instance of Decorator with the applied color mode
+      # @rbs (Integer mode) -> Decorator
+      def with_mode(mode)
+        Decorator.new(mode:)
+      end
+    end
+  end
+end