unmagic-color 0.1.0 → 0.2.1

data/lib/unmagic/color/console/banner.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    module Console
+      # Renders the colorized ASCII art banner for the console.
+      #
+      # @example
+      #   puts Unmagic::Color::Console::Banner.new.render
+      class Banner
+        # ASCII art lines for the banner
+        LINES = [
+          "                                                              ▄▄",
+          "                                  ▀▀                          ██",
+          " ██ ██ ████▄ ███▄███▄  ▀▀█▄ ▄████ ██  ▄████       ▄████ ▄███▄ ██ ▄███▄ ████▄",
+          " ██ ██ ██ ██ ██ ██ ██ ▄█▀██ ██ ██ ██  ██    ▀▀▀▀▀ ██    ██ ██ ██ ██ ██ ██ ▀▀",
+          " ▀██▀█ ██ ██ ██ ██ ██ ▀█▄██ ▀████ ██▄ ▀████       ▀████ ▀███▀ ██ ▀███▀ ██",
+          "                               ██",
+          "                             ▀▀▀",
+        ].freeze
+
+        # Gradient colors for the banner (magenta -> cyan -> green -> yellow -> red)
+        COLORS = ["#ff00ff", "#00ffff", "#00ff00", "#ffff00", "#ff0000"].freeze
+
+        # Render the banner with gradient coloring.
+        #
+        # @return [String] The colorized banner
+        def render
+          gradient = Gradient.linear(COLORS, direction: "left to right")
+
+          height = LINES.length
+          width = LINES.map(&:length).max
+
+          bitmap = gradient.rasterize(width: width, height: height)
+
+          LINES.each_with_index.map do |line, y|
+            line.chars.each_with_index.map do |char, x|
+              if char.strip.empty?
+                char
+              else
+                color = bitmap.pixels[y][x]
+                "\e[#{color.to_ansi}m#{char}\e[0m"
+              end
+            end.join
+          end.join("\n")
+        end
+
+        # @return [String] The rendered banner
+        def to_s
+          render
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/console/card.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "highlighter"
+
+module Unmagic
+  class Color
+    # Console output utilities for rendering colors in terminals.
+    module Console
+      # Renders a comprehensive "profile card" for a color.
+      #
+      # Displays the color's values in all color spaces (RGB, HSL, OKLCH),
+      # harmony colors, and variations (shades, tints, tones).
+      #
+      # @example Basic usage
+      #   card = Unmagic::Color::Console::Card.new("#FF5733")
+      #   puts card.render
+      #
+      # @example With a color object
+      #   color = Unmagic::Color.parse("rebeccapurple")
+      #   puts Unmagic::Color::Console::Card.new(color)
+      class Card
+        # Width of the card in characters (excluding box borders)
+        WIDTH = 72
+
+        def initialize(color)
+          @color = Color.parse(color)
+          @highlighter = Highlighter.new
+        end
+
+        # Render the color profile card as a string.
+        #
+        # @return [String] The formatted card with ANSI color codes
+        def render
+          lines = []
+          lines << top_border
+          lines.concat(header_rows)
+          lines << separator
+          lines.concat(harmony_rows)
+          lines << separator
+          lines.concat(variation_rows)
+          lines << bottom_border
+          lines.join("\n")
+        end
+
+        # @return [String] The rendered card
+        def to_s
+          render
+        end
+
+        private
+
+        # Box drawing characters
+        def top_border
+          "┌#{"─" * WIDTH}┐"
+        end
+
+        def bottom_border
+          "└#{"─" * WIDTH}┘"
+        end
+
+        def separator
+          "├#{"─" * WIDTH}┤"
+        end
+
+        def row(content)
+          visible_length = content.gsub(/\e\[[0-9;]*m/, "").length
+          padding = WIDTH - visible_length - 1
+          "│ #{content}#{" " * [padding, 0].max}│"
+        end
+
+        # Generate a color swatch (colored block)
+        def swatch(color, width: 2)
+          "\e[#{color.to_ansi}m#{"█" * width}\e[0m"
+        end
+
+        # Generate multiple swatches for an array of colors
+        def swatches(colors)
+          colors.map { |c| swatch(c) }.join(" ")
+        end
+
+        # Header with text on left, color swatch on right (same alignment as variations)
+        def header_rows
+          rgb = @color.to_rgb
+          hsl = @color.to_hsl
+          oklch = @color.to_oklch
+
+          left_width = 40 # Same as variation blocks
+          swatch_width = WIDTH - left_width - 2 # -2 for space before row end and right margin
+
+          color_block = swatch(@color, width: swatch_width)
+
+          [
+            row("#{rgb.to_hex.upcase.ljust(left_width)}#{color_block}"),
+            row("#{"rgb(#{rgb.red.value}, #{rgb.green.value}, #{rgb.blue.value})".ljust(left_width)}#{color_block}"),
+            row("#{"hsl(#{hsl.hue.value.round}, #{hsl.saturation.value.round}%, #{hsl.lightness.value.round}%)".ljust(left_width)}#{color_block}"),
+            row("#{"oklch(#{format("%.2f", oklch.lightness)} #{format("%.2f", oklch.chroma.value)} #{oklch.hue.value.round})".ljust(left_width)}#{color_block}"),
+          ]
+        end
+
+        # Calculate WCAG contrast ratio between two luminance values
+        def contrast_ratio(lum1, lum2)
+          lighter = [lum1, lum2].max
+          darker = [lum1, lum2].min
+          (lighter + 0.05) / (darker + 0.05)
+        end
+
+        # Harmony color rows
+        def harmony_rows
+          rows = []
+          rows.concat(variation_block("Complementary", "complementary", @color.complementary))
+          rows.concat(variation_block("Analogous", "analogous", @color.analogous))
+          rows.concat(variation_block("Triadic", "triadic", @color.triadic))
+          rows.concat(variation_block("Split Complementary", "split_complementary", @color.split_complementary))
+          rows.concat(variation_block("Tetradic Square", "tetradic_square", @color.tetradic_square))
+          rows.concat(variation_block("Tetradic Rectangle", "tetradic_rectangle", @color.tetradic_rectangle, last: true))
+          rows
+        end
+
+        # Variation rows (shades, tints, tones, monochromatic)
+        def variation_rows
+          rows = []
+          rows.concat(variation_block("Shades", "shades", @color.shades))
+          rows.concat(variation_block("Tints", "tints", @color.tints))
+          rows.concat(variation_block("Tones", "tones", @color.tones))
+          rows.concat(variation_block("Monochromatic", "monochromatic", @color.monochromatic, last: true))
+          rows
+        end
+
+        # Format a variation block with name, code, swatches and hex values
+        def variation_block(name, method_name, colors, last: false)
+          colors_array = colors.is_a?(Array) ? colors : [colors]
+          hex_value = @color.to_rgb.to_hex.upcase
+
+          # Build the code snippet (dimmed)
+          code = "parse(\"#{hex_value}\").#{method_name}"
+          dim_code = @highlighter.comment(code)
+
+          # Calculate left column width for alignment (same as header)
+          left_width = 40
+          total_swatch_width = WIDTH - left_width - 2 # -2 for space and right margin
+
+          # Auto-balance swatch widths based on number of colors
+          swatch_width = total_swatch_width / colors_array.length
+          swatch_row = colors_array.map { |c| swatch(c, width: swatch_width) }.join
+
+          # Pad title and code to left column, swatches on right
+          title_padded = name.ljust(left_width)
+          code_padded = dim_code.ljust(left_width + dim_code.length - visible_length(dim_code))
+
+          rows = [
+            row("#{title_padded}#{swatch_row}"),
+            row("#{code_padded}#{swatch_row}"),
+          ]
+          rows << row("") unless last
+          rows
+        end
+
+        # Calculate visible length (excluding ANSI codes)
+        def visible_length(str)
+          str.gsub(/\e\[[0-9;]*m/, "").length
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/console/help.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative "highlighter"
+
+module Unmagic
+  class Color
+    module Console
+      # Renders the help text for the console.
+      #
+      # @example
+      #   puts Unmagic::Color::Console::Help.new.render
+      class Help
+        # Render the help text with syntax highlighting.
+        #
+        # @return [String] The formatted help text
+        def render
+          link = highlighter.link("https://github.com/unreasonable-magic/unmagic-color")
+
+          code = highlighter.highlight(<<~RUBY)
+            # Parse colors
+            parse("#ff5733")
+            rgb(255, 87, 51)
+            hsl(9, 100, 60)
+            oklch(0.65, 0.22, 30)
+            parse("rebeccapurple")
+
+            # Manipulate colors
+            color = parse("#ff5733")
+            color.lighten(0.1)
+            color.darken(0.1)
+            color.saturate(0.1)
+            color.desaturate(0.1)
+            color.rotate(30)
+
+            # Convert between formats
+            color.to_rgb
+            color.to_hsl
+            color.to_oklch
+            color.to_hex
+            color.to_css_oklch
+
+            # Create gradients
+            gradient(:linear, ["#FF0000", "#0000FF"]).rasterize(width: 10).pixels[0].map(&:to_hex)
+
+            # Helpers
+            rgb(255, 87, 51)
+            hsl(9, 100, 60)
+            oklch(0.65, 0.22, 30)
+            parse("#ff5733")
+            gradient(:linear, ["#FF0000", "#0000FF"])
+            percentage(50)
+          RUBY
+
+          "#{link}\n\n#{code}"
+        end
+
+        # @return [String] The rendered help text
+        def to_s
+          render
+        end
+
+        private
+
+        def highlighter
+          @highlighter ||= Highlighter.new
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/console/highlighter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    module Console
+      # Simple syntax highlighter for Ruby code snippets.
+      #
+      # Highlights strings, numbers, symbols, and comments
+      # using ANSI color codes.
+      #
+      # @example Basic usage
+      #   hl = Unmagic::Color::Console::Highlighter.new
+      #   puts hl.highlight('color.to_rgb.to_s')
+      #   puts hl.comment('# This is a comment')
+      #
+      # @example With custom colors
+      #   hl = Unmagic::Color::Console::Highlighter.new(colors: { string: "#00FF00" })
+      #   puts hl.highlight('parse("#FF0000")')
+      class Highlighter
+        # Default colors for syntax highlighting
+        DEFAULT = {
+          string: "#00FF00",
+          number: "#FF00FF",
+          symbol: "#FFFF00",
+          comment: "#696969",
+        }.freeze
+
+        # @param mode [Symbol] ANSI color mode (:truecolor, :palette256, :palette16)
+        # @param colors [Hash] Color overrides (keys: :string, :number, :symbol, :comment)
+        def initialize(mode: :palette16, colors: DEFAULT)
+          @mode = mode
+          @colors = DEFAULT.merge(colors)
+        end
+
+        # Highlight a code snippet with syntax coloring.
+        #
+        # Supports multi-line input. Lines starting with # are treated as comments.
+        #
+        # @param code [String] Ruby code to highlight (single or multi-line)
+        # @return [String] Code with ANSI color codes
+        def highlight(code)
+          code.lines.map { |line| highlight_line(line.chomp) }.join("\n")
+        end
+
+        private
+
+        def highlight_line(line)
+          # Don't highlight if already contains ANSI codes
+          return line if line.include?("\e[")
+
+          # Treat lines starting with # as comments
+          return comment(line) if line.start_with?("#")
+
+          # Empty lines pass through
+          return line if line.empty?
+
+          result = line
+
+          # Protect strings first by replacing with placeholders
+          strings = []
+          result = result.gsub(/(".*?")/) do
+            strings << Regexp.last_match(1)
+            "\x00STRING#{strings.length - 1}\x00"
+          end
+
+          # Now highlight other elements (won't match inside strings)
+          result = result
+            .gsub(/\b(\d+\.?\d*%?)/) { colorize(Regexp.last_match(1), :number) }
+            .gsub(/(:[a-z_]+|[a-z_]+:)/) { colorize(Regexp.last_match(1), :symbol) }
+
+          # Restore and highlight strings
+          strings.each_with_index do |str, i|
+            result = result.gsub("\x00STRING#{i}\x00", colorize(str, :string))
+          end
+
+          result
+        end
+
+        public
+
+        # Format text as a comment.
+        #
+        # @param text [String] Comment text
+        # @return [String] Gray-colored text
+        def comment(text)
+          colorize(text, :comment)
+        end
+
+        # Colorize text with a specific color.
+        #
+        # @param text [String] Text to colorize
+        # @param key [Symbol] Color key from the colors hash
+        # @return [String] Text with ANSI color codes
+        def colorize(text, key)
+          color = Color.parse(@colors[key])
+          "\e[#{color.to_ansi(mode: @mode)}m#{text}\e[0m"
+        end
+
+        # Format text as a clickable hyperlink.
+        #
+        # Uses ANSI palette16 blue with underline, plus OSC 8 hyperlink
+        # sequence for iTerm2 and other modern terminals.
+        #
+        # @param url [String] The URL to link to
+        # @param text [String] The display text (defaults to url)
+        # @return [String] Styled, clickable link
+        def link(url, text = url)
+          # ANSI palette16 blue (34) + underline (4)
+          "\e[4;34m\e]8;;#{url}\a#{text}\e]8;;\a\e[0m"
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/gradient/base.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    module Gradient
+      # Base class for gradient implementations.
+      #
+      # Provides shared functionality for all gradient types. Subclasses must
+      # override `color_class` and `validate_color_types` to specify their color space.
+      #
+      # ## Subclass Requirements
+      #
+      # Subclasses must implement:
+      # - `.color_class` - Returns the color class (RGB, HSL, or OKLCH)
+      # - `#validate_color_types(stops)` - Validates all stops have correct color type
+      # - `#rasterize` - Generates a Bitmap from the gradient
+      #
+      # ## Examples
+      #
+      #   # Subclasses use this base class
+      #   class RGB::Gradient::Linear < Gradient::Base
+      #     def self.color_class
+      #       Unmagic::Color::RGB
+      #     end
+      #
+      #     def validate_color_types(stops)
+      #       # Validation logic...
+      #     end
+      #
+      #     def rasterize
+      #       # Rasterization logic...
+      #     end
+      #   end
+      class Base
+        # Error raised for gradient base class issues.
+        class Error < Color::Error; end
+
+        attr_reader :stops, :direction
+
+        class << self
+          # Get the color class for this gradient type.
+          #
+          # Subclasses must override this to return their color class.
+          #
+          # @return [Class] The color class (RGB, HSL, or OKLCH)
+          # @raise [NotImplementedError] If not overridden by subclass
+          def color_class
+            raise NotImplementedError, "Subclasses must define color_class"
+          end
+
+          # Build a gradient from colors or color/position tuples.
+          #
+          # Convenience factory method that converts colors to Stop objects
+          # and creates a gradient. Accepts both color objects and strings
+          # (strings are parsed using the color class's parse method).
+          #
+          # Works like CSS linear-gradient - you can mix positioned and non-positioned colors.
+          # Non-positioned colors auto-balance between their surrounding positioned neighbors.
+          #
+          # @param colors_or_tuples [Array] Array of colors or [color, position] pairs (can be mixed)
+          # @param direction [String, Numeric, Degrees, Direction, nil] Optional gradient direction
+          #   - Direction strings: "to top", "from left to right", "45deg", "90°"
+          #   - Numeric degrees: 45, 90, 180
+          #   - Degrees/Direction instances
+          #   - Defaults to "to bottom" (180°) if omitted
+          # @return [Base] New gradient instance
+          #
+          # @example All auto-balanced positions
+          #   RGB::Gradient::Linear.build(["#FF0000", "#00FF00", "#0000FF"])
+          #   # Positions: 0.0, 0.5, 1.0
+          #
+          # @example All explicit positions
+          #   RGB::Gradient::Linear.build([["#FF0000", 0.0], ["#00FF00", 0.3], ["#0000FF", 1.0]])
+          #
+          # @example Mixed positions (like CSS linear-gradient)
+          #   RGB::Gradient::Linear.build(["#FF0000", ["#FFFF00", 0.3], "#00FF00", ["#0000FF", 0.9], "#FF00FF"])
+          #   # Positions: 0.0, 0.3, 0.6, 0.9, 1.0
+          #   # (red at start, yellow at 30%, green auto-balances at 60%, blue at 90%, purple at end)
+          #
+          # @example With direction keyword
+          #   RGB::Gradient::Linear.build(["#FF0000", "#0000FF"], direction: "to right")
+          #   RGB::Gradient::Linear.build(["#FF0000", "#0000FF"], direction: "from left to right")
+          #
+          # @example With numeric direction
+          #   RGB::Gradient::Linear.build(["#FF0000", "#0000FF"], direction: 45)
+          #   RGB::Gradient::Linear.build(["#FF0000", "#0000FF"], direction: "90deg")
+          def build(colors_or_tuples, direction: nil)
+            # Parse colors and detect which have explicit positions
+            parsed = colors_or_tuples.map do |item|
+              if item.is_a?(::Array)
+                # Explicit position tuple
+                color_or_string, position = item
+                color = if color_or_string.is_a?(::String)
+                  # Use universal parser for strings (handles named colors, hex, rgb(), hsl(), etc.)
+                  parsed_color = Unmagic::Color[color_or_string]
+                  # Convert to the gradient's color space if needed
+                  convert_to_color_space(parsed_color)
+                else
+                  color_or_string
+                end
+                { color: color, position: position }
+              else
+                # No position, will auto-balance
+                color = if item.is_a?(::String)
+                  # Use universal parser for strings
+                  parsed_color = Unmagic::Color[item]
+                  # Convert to the gradient's color space if needed
+                  convert_to_color_space(parsed_color)
+                else
+                  item
+                end
+                { color: color, position: nil }
+              end
+            end
+
+            # Auto-balance positions for items without explicit positions
+            # Pass 1: Set first and last items if they don't have positions
+            unless parsed.first[:position]
+              parsed.first[:position] = 0.0
+            end
+            unless parsed.last[:position]
+              parsed.last[:position] = 1.0
+            end
+
+            # Pass 2: Auto-balance middle items
+            parsed.each_with_index do |item, i|
+              next if item[:position] # Already has position
+
+              # Find previous positioned stop
+              prev_pos = nil
+              prev_index = nil
+              (i - 1).downto(0) do |j|
+                if parsed[j][:position]
+                  prev_pos = parsed[j][:position]
+                  prev_index = j
+                  break
+                end
+              end
+
+              # Find next positioned stop
+              next_pos = nil
+              next_index = nil
+              ((i + 1)...parsed.length).each do |j|
+                if parsed[j][:position]
+                  next_pos = parsed[j][:position]
+                  next_index = j
+                  break
+                end
+              end
+
+              # Count items in this unpositioned group
+              group_size = next_index - prev_index - 1
+              group_index = i - prev_index - 1
+
+              # Evenly distribute within the range
+              item[:position] = prev_pos + (next_pos - prev_pos) * (group_index + 1) / (group_size + 1).to_f
+            end
+
+            # Create Stop objects
+            stops = parsed.map do |item|
+              Unmagic::Color::Gradient::Stop.new(color: item[:color], position: item[:position])
+            end
+
+            new(stops, direction: direction)
+          end
+
+          private
+
+          # Convert a color to this gradient's color space.
+          #
+          # @param color [Color] The color to convert
+          # @return [Color] The color in the gradient's color space
+          def convert_to_color_space(color)
+            target_class = color_class
+            return color if color.is_a?(target_class)
+
+            # Convert to the target color space
+            case target_class.name
+            when "Unmagic::Color::RGB"
+              color.to_rgb
+            when "Unmagic::Color::HSL"
+              color.to_hsl
+            when "Unmagic::Color::OKLCH"
+              color.to_oklch
+            else
+              color
+            end
+          end
+        end
+
+        # Create a new gradient.
+        #
+        # @param stops [Array<Stop>] Array of color stops
+        # @param direction [Direction, nil] Optional Direction instance (defaults to TOP_TO_BOTTOM)
+        #
+        # @raise [Error] If stops is not an array
+        # @raise [Error] If there are fewer than 2 stops
+        # @raise [Error] If any stop is not a Stop object
+        # @raise [Error] If stops are not sorted by position
+        def initialize(stops, direction: nil)
+          raise Error, "stops must be an array" unless stops.is_a?(Array)
+          raise Error, "must have at least 2 stops" if stops.length < 2
+
+          stops.each_with_index do |stop, i|
+            unless stop.is_a?(Unmagic::Color::Gradient::Stop)
+              raise Error, "stops[#{i}] must be a Stop object"
+            end
+          end
+
+          validate_color_types(stops)
+
+          stops.each_cons(2) do |a, b|
+            if a.position > b.position
+              raise Error, "stops must be sorted by position"
+            end
+          end
+
+          @stops = stops
+          @direction = direction
+        end
+
+        private
+
+        # Validate that all stops have the correct color type.
+        #
+        # Subclasses must override this to check color types.
+        #
+        # @param stops [Array<Stop>] Array of stops to validate
+        # @raise [NotImplementedError] If not overridden by subclass
+        def validate_color_types(stops)
+          raise NotImplementedError, "Subclasses must implement validate_color_types"
+        end
+
+        # Find the two stops that bracket a given position.
+        #
+        # Returns the start and end stops for the segment containing the position.
+        # Used during interpolation to find which colors to blend.
+        #
+        # @param position [Float] Position to find (0.0-1.0)
+        # @return [Array<Stop, Stop>] The [start_stop, end_stop] that bracket the position
+        def find_bracket_stops(position)
+          @stops.each_cons(2) do |start_stop, end_stop|
+            if position >= start_stop.position && position <= end_stop.position
+              return [start_stop, end_stop]
+            end
+          end
+          [@stops[-2], @stops[-1]]
+        end
+      end
+    end
+  end
+end