poetry-charts 0.0.2

data/lib/poetry/charts/geometry/curve.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Geometry
+      # The curve state machines - including the `_line`
+      # undefined/0/1/NaN dance that decides where subpaths close (JS
+      # truthiness via Geometry.js_truthy?; `1 - undefined` becomes NaN
+      # via js_flip). The set matches the families' curve: whitelist:
+      # linear, step (+before/after), natural, and monotone_x.
+      #
+      # @example Build a curve writing into a fresh path buffer
+      #   Poetry::Charts::Geometry::Curve.build(:natural, Path.new)
+      module Curve
+        # Curve name -> builder for its state machine.
+        REGISTRY = {
+          linear: ->(context) { Linear.new(context) },
+          step: ->(context) { Step.new(context, 0.5) },
+          step_before: ->(context) { Step.new(context, 0.0) },
+          step_after: ->(context) { Step.new(context, 1.0) },
+          natural: ->(context) { Natural.new(context) },
+          monotone_x: ->(context) { MonotoneX.new(context) }
+        }.freeze
+
+        module_function
+
+        # A curve state machine writing into the given path context.
+        def build(name, context)
+          builder = REGISTRY[name.to_sym] or
+            raise ArgumentError, "unknown curve #{name.inspect} (one of #{REGISTRY.keys.join(", ")})"
+          builder.call(context)
+        end
+
+        # JS `1 - line` where line may be undefined (nil) or NaN.
+        def self.js_flip(line)
+          return Float::NAN if line.nil? || (line.is_a?(Float) && line.nan?)
+
+          1 - line
+        end
+
+        # Shared area/line bookkeeping (identical across all four curves).
+        # @api private
+        module LineState
+          def area_start
+            @line = 0
+          end
+
+          def area_end
+            @line = Float::NAN
+          end
+
+          private
+
+          def line_truthy?
+            Geometry.js_truthy?(@line)
+          end
+
+          # JS: this._line || (this._line !== 0 && <extra>)
+          def close_on_line_end?(extra)
+            line_truthy? || (@line != 0 && extra)
+          end
+
+          def flip_line
+            @line = Curve.js_flip(@line)
+          end
+        end
+
+        # Straight segments between points.
+        # @api private
+        class Linear
+          include LineState
+
+          def initialize(context)
+            @context = context
+            @line = nil
+          end
+
+          def line_start
+            @point = 0
+          end
+
+          def line_end
+            @context.close_path if close_on_line_end?(@point == 1)
+            flip_line
+          end
+
+          def point(x, y)
+            x = x.to_f
+            y = y.to_f
+            case @point
+            when 0
+              @point = 1
+              line_truthy? ? @context.line_to(x, y) : @context.move_to(x, y)
+            else
+              @point = 2
+              @context.line_to(x, y)
+            end
+          end
+        end
+
+        # Right-angle steps between points; t places the riser (0 before,
+        # 0.5 midway, 1 after).
+        # @api private
+        class Step
+          include LineState
+
+          def initialize(context, t)
+            @context = context
+            @t = t
+            @line = nil
+          end
+
+          def line_start
+            @x = @y = Float::NAN
+            @point = 0
+          end
+
+          def line_end
+            @context.line_to(@x, @y) if @t.positive? && @t < 1 && @point == 2
+            @context.close_path if close_on_line_end?(@point == 1)
+            # JS: if (this._line >= 0) - false for undefined and NaN.
+            return unless !@line.nil? && !(@line.is_a?(Float) && @line.nan?) && @line >= 0
+
+            @t = 1 - @t
+            @line = 1 - @line
+          end
+
+          def point(x, y)
+            x = x.to_f
+            y = y.to_f
+            case @point
+            when 0
+              @point = 1
+              line_truthy? ? @context.line_to(x, y) : @context.move_to(x, y)
+            else
+              @point = 2 if @point == 1
+              if @t <= 0
+                @context.line_to(@x, y)
+                @context.line_to(x, y)
+              else
+                x1 = (@x * (1 - @t)) + (x * @t)
+                @context.line_to(x1, @y)
+                @context.line_to(x1, y)
+              end
+            end
+            @x = x
+            @y = y
+          end
+        end
+
+        # A natural cubic spline through every point.
+        # @api private
+        class Natural
+          include LineState
+
+          def initialize(context)
+            @context = context
+            @line = nil
+          end
+
+          def line_start
+            @xs = []
+            @ys = []
+          end
+
+          def line_end
+            x = @xs
+            y = @ys
+            n = x.length
+
+            if n.positive?
+              line_truthy? ? @context.line_to(x[0], y[0]) : @context.move_to(x[0], y[0])
+              if n == 2
+                @context.line_to(x[1], y[1])
+              elsif n > 2
+                px = Natural.control_points(x)
+                py = Natural.control_points(y)
+                (0...(n - 1)).each do |i0|
+                  i1 = i0 + 1
+                  @context.bezier_curve_to(px[0][i0], py[0][i0], px[1][i0], py[1][i0], x[i1], y[i1])
+                end
+              end
+            end
+
+            @context.close_path if close_on_line_end?(n == 1)
+            flip_line
+            @xs = @ys = nil
+          end
+
+          def point(x, y)
+            @xs << x.to_f
+            @ys << y.to_f
+          end
+
+          # The tridiagonal control-point solve
+          # (https://www.particleincell.com/2012/bezier-splines/).
+          def self.control_points(x)
+            n = x.length - 1
+            a = Array.new(n)
+            b = Array.new(n)
+            r = Array.new(n)
+
+            a[0] = 0.0
+            b[0] = 2.0
+            r[0] = x[0] + (2 * x[1])
+            (1...(n - 1)).each do |i|
+              a[i] = 1.0
+              b[i] = 4.0
+              r[i] = (4 * x[i]) + (2 * x[i + 1])
+            end
+            a[n - 1] = 2.0
+            b[n - 1] = 7.0
+            r[n - 1] = (8 * x[n - 1]) + x[n]
+
+            (1...n).each do |i|
+              m = a[i] / b[i - 1]
+              b[i] -= m
+              r[i] -= m * r[i - 1]
+            end
+
+            a[n - 1] = r[n - 1] / b[n - 1]
+            (n - 2).downto(0) { |i| a[i] = (r[i] - a[i + 1]) / b[i] }
+            b[n - 1] = (x[n] + a[n - 1]) / 2
+            (0...(n - 1)).each { |i| b[i] = (2 * x[i + 1]) - a[i + 1] }
+
+            [a, b]
+          end
+        end
+
+        # A cubic that preserves monotonicity in x - no overshoot between
+        # points.
+        # @api private
+        class MonotoneX
+          include LineState
+
+          def initialize(context)
+            @context = context
+            @line = nil
+          end
+
+          def line_start
+            @x0 = @x1 = @y0 = @y1 = @t0 = Float::NAN
+            @point = 0
+          end
+
+          def line_end
+            case @point
+            when 2 then @context.line_to(@x1, @y1)
+            when 3 then emit(@t0, slope2(@t0))
+            end
+            @context.close_path if close_on_line_end?(@point == 1)
+            flip_line
+          end
+
+          def point(x, y)
+            x = x.to_f
+            y = y.to_f
+            return if x == @x1 && y == @y1 # ignore coincident points
+
+            case @point
+            when 0
+              @point = 1
+              line_truthy? ? @context.line_to(x, y) : @context.move_to(x, y)
+              t1 = Float::NAN
+            when 1
+              @point = 2
+              t1 = Float::NAN
+            when 2
+              @point = 3
+              t1 = slope3(x, y)
+              emit(slope2(t1), t1)
+            else
+              t1 = slope3(x, y)
+              emit(@t0, t1)
+            end
+
+            @x0 = @x1
+            @x1 = x
+            @y0 = @y1
+            @y1 = y
+            @t0 = t1
+          end
+
+          private
+
+          def sign(value)
+            value.negative? ? -1.0 : 1.0
+          end
+
+          # Steffen (1990) monotone tangent slopes. The JS `(h0 || h1 < 0 &&
+          # -0)` denominator trick yields signed zero when h0 is 0, so the
+          # division produces the correctly signed infinity.
+          def slope3(x2, y2)
+            h0 = @x1 - @x0
+            h1 = x2 - @x1
+            d0 = if h0.zero? && !h0.nan?
+                   h1.negative? ? -0.0 : 0.0
+                 else
+                   h0
+                 end
+            d1 = if h1.zero? && !h1.nan?
+                   h0.negative? ? -0.0 : 0.0
+                 else
+                   h1
+                 end
+            s0 = (@y1 - @y0) / d0
+            s1 = (y2 - @y1) / d1
+            p = ((s0 * h1) + (s1 * h0)) / (h0 + h1)
+            result = (sign(s0) + sign(s1)) * [s0.abs, s1.abs, 0.5 * p.abs].min
+            result.nan? ? 0.0 : result
+          end
+
+          def slope2(t)
+            h = @x1 - @x0
+            Geometry.js_truthy?(h) ? (((3 * (@y1 - @y0)) / h) - t) / 2 : t
+          end
+
+          # Hermite -> cubic Bezier (control points at thirds).
+          def emit(t0, t1)
+            dx = (@x1 - @x0) / 3
+            @context.bezier_curve_to(@x0 + dx, @y0 + (dx * t0), @x1 - dx, @y1 - (dx * t1), @x1, @y1)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/charts/geometry/line.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Geometry
+      # The line generator: data -> SVG path string through a curve state
+      # machine, with defined-gaps starting new subpaths (a single toggle
+      # loop). Accessors are lambdas (d, i), symbols/strings (hash key
+      # lookup), or numeric constants; x/y default to the [x, y] pair
+      # convention.
+      #
+      # @example
+      #   Poetry::Charts::Geometry::Line.new(curve: :monotone_x).path(points)
+      class Line
+        def initialize(x: nil, y: nil, curve: :linear, defined: nil, digits: 3)
+          @x = Accessor.wrap(x) { |d, _i| d[0] }
+          @y = Accessor.wrap(y) { |d, _i| d[1] }
+          @defined = Accessor.wrap(defined) { |_d, _i| true }
+          @curve = curve
+          @digits = digits
+        end
+
+        # The SVG path for the data (nil when nothing was defined).
+        #
+        # @param data [Enumerable]
+        # @return [String, nil]
+        def path(data)
+          data = data.to_a
+          n = data.length
+          buffer = Path.new(digits: @digits)
+          output = Curve.build(@curve, buffer)
+          defined0 = false
+
+          (0..n).each do |i|
+            d = i < n ? data[i] : nil
+            if (!(i < n && @defined.call(d, i))) == defined0
+              defined0 = !defined0
+              defined0 ? output.line_start : output.line_end
+            end
+            output.point(@x.call(d, i).to_f, @y.call(d, i).to_f) if defined0
+          end
+
+          buffer.empty? ? nil : buffer.to_s
+        end
+
+        # Accessor coercion shared by the generators.
+        module Accessor
+          module_function
+
+          # A (d, i) lambda from a lambda, key, constant, or the default.
+          def wrap(value, &default)
+            case value
+            when nil then default
+            when Proc then value.arity == 1 ? ->(d, _i) { value.call(d) } : value
+            when Symbol, String then ->(d, _i) { d[value] }
+            when Numeric then ->(_d, _i) { value }
+            else raise ArgumentError, "bad accessor #{value.inspect}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/poetry/charts/geometry/nice_ticks.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Poetry
+  module Charts
+    module Geometry
+      # Adapted from an MIT-licensed source (source and license in
+      # THIRD_PARTY_NOTICES.md).
+      #
+      # The nice-ticks algorithm on BigDecimal, so the tick values stay
+      # decimal-exact. Every operation is decimal, not binary: values
+      # construct from the double's shortest decimal string, remainders
+      # truncate with the dividend's sign (#remainder), division carries
+      # 20 significant digits (PRECISION), and digit counts come from
+      # BigDecimal#exponent (exactly floor(log10) + 1).
+      #
+      # Oracle: translated spec cases pin the expected tick values.
+      #
+      # @example Nice a raw domain into tick values
+      #   Poetry::Charts::Geometry::NiceTicks.nice_ticks([0, 97], 5)
+      module NiceTicks
+        # Significant digits carried through every division.
+        PRECISION = 20
+        # The step multiples the :snap125 mode snaps to.
+        SNAP_STEPS = [1r, 2r, 2.5r, 5r].map { |step| BigDecimal(step, 10) }.freeze
+
+        module_function
+
+        # Coerce to BigDecimal via the double's shortest decimal string.
+        def dec(value)
+          value.is_a?(BigDecimal) ? value : BigDecimal(value.to_f.to_s)
+        end
+
+        # Digit count: 1 for [1,10), 0 for [0.1,1), -1 for [0.01,0.1)...
+        # BigDecimal#exponent IS floor(log10(|v|)) + 1, exactly.
+        def digit_count(value)
+          return 1 if value.zero?
+
+          dec(value).exponent
+        end
+
+        # [start, end) with a fixed decimal step.
+        def range_step(start, stop, step)
+          num = start
+          result = []
+          i = 0
+          while num < stop && i < 100_000
+            result << num.to_f
+            num += step
+            i += 1
+          end
+          result
+        end
+
+        # The interval sorted ascending.
+        def valid_interval(min, max)
+          min > max ? [max, min] : [min, max]
+        end
+
+        # The default step function: amend the rough step to a value that
+        # reads well at its order of magnitude.
+        def adaptive_step(rough_step, allow_decimals, correction_factor)
+          return BigDecimal(0) if rough_step <= 0
+
+          digits = digit_count(rough_step.to_f)
+          digit_count_value = BigDecimal(10)**digits
+          step_ratio = rough_step.div(digit_count_value, PRECISION)
+          step_ratio_scale = digits == 1 ? BigDecimal("0.1") : BigDecimal("0.05")
+          amend_step_ratio = (BigDecimal(step_ratio.div(step_ratio_scale, PRECISION).to_f.ceil) +
+                              correction_factor) * step_ratio_scale
+          format_step = amend_step_ratio * digit_count_value
+
+          allow_decimals ? BigDecimal(format_step.to_f.to_s) : BigDecimal(format_step.to_f.ceil)
+        end
+
+        # The opt-in snap125 step: snap to 1 / 2 / 2.5 / 5 at each order of
+        # magnitude.
+        def snap125_step(rough_step, allow_decimals, correction_factor)
+          return BigDecimal(0) if rough_step <= 0
+
+          # Math.floor(abs.log(10)) == exponent - 1, exactly.
+          exponent = dec(rough_step.to_f).abs.exponent - 1
+          magnitude = BigDecimal(10)**exponent
+          normalized = rough_step.div(magnitude, PRECISION).to_f
+
+          nice_index = SNAP_STEPS.index { |step| step.to_f >= normalized - 1e-10 }
+          if nice_index.nil?
+            magnitude *= 10
+            nice_index = 0
+          end
+
+          nice_index += correction_factor
+          if nice_index >= SNAP_STEPS.length
+            extra_magnitude = nice_index / SNAP_STEPS.length
+            nice_index %= SNAP_STEPS.length
+            magnitude *= BigDecimal(10)**extra_magnitude
+          end
+
+          format_step = SNAP_STEPS[nice_index] * magnitude
+          allow_decimals ? format_step : BigDecimal(format_step.to_f.ceil)
+        end
+
+        # The step function a mode selects.
+        def step_function(mode)
+          mode == :snap125 ? method(:snap125_step) : method(:adaptive_step)
+        end
+
+        # Ticks when min == max: center a window of tickCount steps on the value.
+        def ticks_of_single_value(value, tick_count, allow_decimals)
+          step = BigDecimal(1)
+          middle = dec(value)
+
+          if middle.frac.nonzero? && allow_decimals
+            abs_value = value.abs
+            if abs_value < 1
+              step = BigDecimal(10)**(digit_count(value) - 1)
+              middle = BigDecimal(middle.div(step, PRECISION).to_f.floor) * step
+            elsif abs_value > 1
+              middle = BigDecimal(value.floor)
+            end
+          elsif value.zero?
+            middle = BigDecimal((tick_count - 1) / 2)
+          elsif !allow_decimals
+            middle = BigDecimal(value.floor)
+          end
+
+          middle_index = (tick_count - 1) / 2
+          Array.new(tick_count) { |i| (middle + (BigDecimal(i - middle_index) * step)).to_f }
+        end
+
+        # The step + tick bounds for an interval (recursive: a correction
+        # factor grows the step until tickCount ticks cover the interval).
+        def calculate_step(min, max, tick_count, allow_decimals, correction_factor = 0, step_fn: method(:adaptive_step))
+          unless ((max - min) / (tick_count - 1)).finite?
+            return { step: BigDecimal(0), tick_min: BigDecimal(0), tick_max: BigDecimal(0) }
+          end
+
+          step = step_fn.call((dec(max) - dec(min)).div(BigDecimal(tick_count - 1), PRECISION),
+                              allow_decimals, correction_factor)
+
+          middle = if 0.between?(min, max)
+                     BigDecimal(0)
+                   else
+                     mid = (dec(min) + dec(max)).div(BigDecimal(2), PRECISION)
+                     mid - mid.remainder(step)
+                   end
+
+          below_count = (middle - dec(min)).div(step, PRECISION).to_f.ceil
+          up_count = (dec(max) - middle).div(step, PRECISION).to_f.ceil
+          scale_count = below_count + up_count + 1
+
+          if scale_count > tick_count
+            return calculate_step(min, max, tick_count, allow_decimals, correction_factor + 1, step_fn:)
+          end
+
+          if scale_count < tick_count
+            up_count += (tick_count - scale_count) if max.positive?
+            below_count += (tick_count - scale_count) unless max.positive?
+          end
+
+          {
+            step: step,
+            tick_min: middle - (BigDecimal(below_count) * step),
+            tick_max: middle + (BigDecimal(up_count) * step)
+          }
+        end
+
+        # Nice ticks for [min, max] - ticks may run OUTSIDE the interval
+        # to stay round.
+        def nice_ticks(domain, tick_count = 6, allow_decimals: true, mode: :auto)
+          min, max = domain
+          count = [tick_count, 2].max
+          cormin, cormax = valid_interval(min, max)
+
+          if cormin == -Float::INFINITY || cormax == Float::INFINITY
+            values = if cormax == Float::INFINITY
+                       [cormin] + Array.new(tick_count - 1, Float::INFINITY)
+                     else
+                       Array.new(tick_count - 1, -Float::INFINITY) + [cormax]
+                     end
+            return min > max ? values.reverse : values
+          end
+
+          return ticks_of_single_value(cormin, tick_count, allow_decimals) if cormin == cormax
+
+          bounds = calculate_step(cormin, cormax, count, allow_decimals, 0, step_fn: step_function(mode))
+          values = range_step(bounds[:tick_min],
+                              bounds[:tick_max] + (BigDecimal("0.1") * bounds[:step]),
+                              bounds[:step])
+
+          min > max ? values.reverse : values
+        end
+
+        # Nice-stepped ticks CONSTRAINED to [min, max] - the domain
+        # boundary always closes the list.
+        def fixed_domain_ticks(domain, tick_count, allow_decimals: true, mode: :auto)
+          min, max = domain
+          cormin, cormax = valid_interval(min, max)
+
+          return [min, max] if cormin == -Float::INFINITY || cormax == Float::INFINITY
+          return [cormin] if cormin == cormax
+
+          count = [tick_count, 2].max
+          step = step_function(mode).call((dec(cormax) - dec(cormin)).div(BigDecimal(count - 1), PRECISION),
+                                          allow_decimals, 0)
+          values = range_step(dec(cormin), dec(cormax), step) + [cormax]
+
+          unless allow_decimals
+            values = values.map { |value| Geometry.js_round(value) }
+            last = values.length - 1
+            values = values[0...last] if last.positive? && values[last] == values[last - 1]
+          end
+
+          min > max ? values.reverse : values
+        end
+      end
+    end
+  end
+end

data/lib/poetry/charts/geometry/path.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Charts
+    module Geometry
+      # The path buffer the shape generators write into: move_to /
+      # line_to / bezier_curve_to / quadratic_curve_to / close_path.
+      # Numbers are rounded to `digits` decimals with JS Math.round
+      # semantics and stringified as JS does (digits defaults to 3) - the
+      # contract that keeps poetry's path strings byte-equal to the
+      # geometry fixtures. Internal cursor state keeps FULL precision
+      # (rounding is output-formatting only).
+      #
+      # The arc/sector verbs are deliberately absent - polar sector paths
+      # are built by Polar, not through this class.
+      #
+      # @example
+      #   path = Path.new
+      #   path.move_to(0, 0)
+      #   path.line_to(10, 20.5)
+      #   path.to_s # => "M0,0L10,20.5"
+      class Path
+        # @param digits [Integer, nil] output rounding decimals; nil disables
+        #   rounding (full-precision output)
+        def initialize(digits: 3)
+          @x0 = @y0 = @x1 = @y1 = nil
+          @data = +""
+          @scale = digits.nil? ? nil : 10**digits
+        end
+
+        # Starts a new subpath at (x, y).
+        def move_to(x, y)
+          x = x.to_f
+          y = y.to_f
+          @x0 = @x1 = x
+          @y0 = @y1 = y
+          @data << "M#{fmt(x)},#{fmt(y)}"
+        end
+
+        # A straight segment to (x, y).
+        def line_to(x, y)
+          x = x.to_f
+          y = y.to_f
+          @x1 = x
+          @y1 = y
+          @data << "L#{fmt(x)},#{fmt(y)}"
+        end
+
+        # A quadratic curve to (x, y) with one control point.
+        def quadratic_curve_to(cpx, cpy, x, y)
+          x = x.to_f
+          y = y.to_f
+          @x1 = x
+          @y1 = y
+          @data << "Q#{fmt(cpx.to_f)},#{fmt(cpy.to_f)},#{fmt(x)},#{fmt(y)}"
+        end
+
+        # A cubic curve to (x, y) with two control points.
+        def bezier_curve_to(cp1x, cp1y, cp2x, cp2y, x, y)
+          x = x.to_f
+          y = y.to_f
+          @x1 = x
+          @y1 = y
+          @data << "C#{fmt(cp1x.to_f)},#{fmt(cp1y.to_f)},#{fmt(cp2x.to_f)},#{fmt(cp2y.to_f)},#{fmt(x)},#{fmt(y)}"
+        end
+
+        # Closes the current subpath back to its start (a no-op before
+        # any move).
+        def close_path
+          return if @x1.nil?
+
+          @x1 = @x0
+          @y1 = @y0
+          @data << "Z"
+        end
+
+        # The accumulated SVG path data.
+        def to_s
+          @data
+        end
+
+        # Whether nothing has been written yet.
+        def empty?
+          @data.empty?
+        end
+
+        private
+
+        def fmt(value)
+          value = ((value * @scale) + 0.5).floor / @scale.to_f if @scale
+          Geometry.js_number(value)
+        end
+      end
+    end
+  end
+end