yarn_skein 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: de030bc1badf27891aebbba5deb39a73ab035fbe4be31842f4e9d2bb8105ecdb
-  data.tar.gz: 9ae3781907723962ea50c3b25a3f98705c321f251f981a6a558b3a81218ed442
+  metadata.gz: 6e58123240286568c5799c6ee0d7ed8572de554f44c4e2cbf653e178be29a181
+  data.tar.gz: bd9aba63f86efb708f7156575d7136d91cd660f05bc857b5a0cb50b8087586b7
 SHA512:
-  metadata.gz: 5c4bbcb7d360334e2f79d733f4d53d2371414f2c6e73bc48b67d1a3e027e2c48a1e822d56fbc424ef6c42dfacbbcd471f00ab55497baac641ea510f4564748a0
-  data.tar.gz: cc0e8ac28ad96f6977471b3fca483989ca8b0e2142040dce66632714c0c3b022d972ec363f395af645f4143a41757357bf48ef362833a399a183d08a0093b708
+  metadata.gz: 7a13f3cde5def54d9bdd85026f2d143a9e3d0e9ca4b76023573839c8fc6f6d1b224580e62eb19907b6559a08391103470efb71fb7e6dba428d1364f64d4ea165
+  data.tar.gz: 398c7cfaa30a61beb4839fda0bc96737023b03df676b1fb85cae9e8854e4d7119e2f32be1de5fe2a86d402ea365450a0547b8749938395f68cb18644b61d5567

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.4.0] - 2026-03-28
+
+### Added
+- `YarnSkein::ColorworkEstimator` for estimating per-color yarn yardage in stranded and intarsia colorwork
+- Supports float overhead calculation for stranded colorwork (default 20%)
+- Per-color breakdown with optional skein calculations when yarn is provided
+- Configurable safety margin (default 10%) consistent with `YardageEstimator`
+
+## [0.3.0] - 2026-03-26
+
+### Added
+- `YarnSkein::Catalog` for loading yarn data from YAML seed files with filtering by brand, weight category, and fiber content
+- `YarnSkein::YardageEstimator` for estimating total yarn yardage from gauge and dimensions
+- Rectangular piece estimation via `for_rectangle(width:, height:)`
+- Stitch/row count estimation via `for_piece(stitches:, rows:)`
+- Configurable safety margin (default 10%) for waste and joining
+- Added `fiber_gauge` as a runtime dependency
 
 ## [0.2.0] - 2026-03-21
 

data/lib/yarn_skein/catalog.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module YarnSkein
+  class Catalog
+    def initialize(data_dir: nil)
+      @data_dir = data_dir || default_data_dir
+      @yarns = nil
+    end
+
+    def all
+      load_yarns
+    end
+
+    def filter(brand: nil, weight_category: nil, fiber: nil)
+      results = all
+      results = results.select { |y| y.brand.downcase == brand.downcase } if brand
+      results = results.select { |y| y.weight_category == weight_category.to_sym } if weight_category
+      results = results.select { |y| y.fiber_content&.contains?(fiber.to_sym) } if fiber
+      results
+    end
+
+    def brands
+      all.map(&:brand).uniq.sort
+    end
+
+    def find(brand:, line:)
+      all.detect { |y| y.brand.downcase == brand.downcase && y.line.downcase == line.downcase }
+    end
+
+    private
+
+    def load_yarns
+      @yarns ||= Dir.glob(File.join(@data_dir, "*.yml")).reject { |f| File.basename(f).start_with?("_") }.flat_map { |file| parse_brand_file(file) }
+    end
+
+    def parse_brand_file(file)
+      data = YAML.safe_load_file(file, permitted_classes: [])
+      brand_name = data["brand"]
+      (data["yarns"] || []).filter_map do |entry|
+        build_yarn(brand_name, entry)
+      end
+    end
+
+    def build_yarn(brand_name, entry)
+      yardage = entry["yardage"]
+      skein_weight = entry["skein_weight"]
+      return nil unless yardage && skein_weight
+
+      fiber_content = nil
+      if entry["fiber_content"] && !entry["fiber_content"].empty?
+        fiber_hash = entry["fiber_content"].transform_keys(&:to_sym).transform_values(&:to_i)
+        fiber_content = FiberBlend.new(fiber_hash)
+      end
+
+      Yarn.new(
+        brand: brand_name,
+        line: entry["line"],
+        yardage: yardage.to_f.yards,
+        skein_weight: skein_weight.to_f.grams,
+        fiber_content: fiber_content
+      )
+    end
+
+    def default_data_dir
+      env_path = ENV["YARN_CATALOG_PATH"]
+      return env_path if env_path
+
+      File.expand_path("../../../../data/yarns", __dir__)
+    end
+  end
+end

data/lib/yarn_skein/colorwork_estimator.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module YarnSkein
+  # Estimates per-color yarn yardage for colorwork techniques.
+  #
+  # Supports stranded (Fair Isle) and intarsia colorwork. Stranded colorwork
+  # adds a float overhead factor because unused colors are carried across the
+  # back of the fabric. Intarsia uses separate yarn sections with no floats.
+  #
+  # @example Stranded colorwork
+  #   estimator = YarnSkein::ColorworkEstimator.new(
+  #     gauge: gauge,
+  #     technique: :stranded
+  #   )
+  #   estimator.estimate(
+  #     width: 40.inches, height: 24.inches,
+  #     colors: { main: 0.60, contrast: 0.40 },
+  #     yarn: yarn
+  #   )
+  #
+  # @example Intarsia colorwork
+  #   estimator = YarnSkein::ColorworkEstimator.new(
+  #     gauge: gauge,
+  #     technique: :intarsia
+  #   )
+  #   estimator.estimate(
+  #     width: 40.inches, height: 24.inches,
+  #     colors: { left: 0.50, right: 0.50 },
+  #     yarn: yarn
+  #   )
+  class ColorworkEstimator
+    TECHNIQUES = %i[stranded intarsia].freeze
+
+    # Default float overhead for stranded colorwork (20%).
+    DEFAULT_FLOAT_OVERHEAD = 0.20
+
+    # Default safety margin (10%), consistent with YardageEstimator.
+    DEFAULT_MARGIN = 0.10
+
+    # @return [FiberGauge::Gauge]
+    attr_reader :gauge
+
+    # @return [Symbol] :stranded or :intarsia
+    attr_reader :technique
+
+    # @param gauge [FiberGauge::Gauge] gauge swatch data
+    # @param technique [Symbol] :stranded or :intarsia
+    def initialize(gauge:, technique:)
+      unless TECHNIQUES.include?(technique)
+        raise ArgumentError, "technique must be one of: #{TECHNIQUES.join(", ")}"
+      end
+
+      @gauge = gauge
+      @technique = technique
+    end
+
+    # Estimates per-color yardage for a colorwork piece.
+    #
+    # @param width [FiberUnits::Length] finished width
+    # @param height [FiberUnits::Length] finished height
+    # @param colors [Hash<Symbol, Float>] color name => proportion (must sum to 1.0)
+    # @param yarn [YarnSkein::Yarn, nil] yarn for skein calculations
+    # @param margin [Float] safety margin (default 10%)
+    # @param float_overhead [Float] extra yarn for floats in stranded work (default 20%)
+    # @return [Hash] per-color breakdown and total
+    def estimate(width:, height:, colors:, yarn: nil, margin: DEFAULT_MARGIN, float_overhead: DEFAULT_FLOAT_OVERHEAD)
+      validate_colors!(colors)
+
+      base_yardage = base_yardage_for(width, height, margin: 0.0)
+      result = {}
+      total_yards = 0.0
+
+      colors.each do |color_name, proportion|
+        color_yards = base_yardage * proportion
+        color_yards *= (1.0 + float_overhead) if technique == :stranded
+        color_yards *= (1.0 + margin)
+        total_yards += color_yards
+
+        entry = {yardage: color_yards.yards}
+        entry[:skeins] = yarn.skeins_required(color_yards.yards) if yarn
+        result[color_name] = entry
+      end
+
+      result[:total] = {yardage: total_yards.yards}
+      result
+    end
+
+    private
+
+    # Compute raw yardage (in float yards) for a rectangle with no margin.
+    def base_yardage_for(width, height, margin:)
+      stitches = gauge.required_stitches(width)
+      rows = gauge.required_rows(height)
+      total_stitches = stitches.value * rows.value
+
+      total_stitches * yards_per_stitch
+    end
+
+    # Yards of yarn consumed per stitch, using the geometric U-loop model.
+    def yards_per_stitch
+      stitch_width_in = 1.0 / gauge.spi
+      stitch_height_in = 1.0 / gauge.rpi
+      (stitch_width_in + (2.0 * stitch_height_in)) / 36.0
+    end
+
+    def validate_colors!(colors)
+      raise ArgumentError, "colors must be a non-empty Hash" unless colors.is_a?(Hash) && !colors.empty?
+
+      total = colors.values.sum
+      unless (total - 1.0).abs < 0.001
+        raise ArgumentError, "color proportions must sum to 1.0 (got #{total})"
+      end
+
+      colors.each do |name, proportion|
+        unless proportion.is_a?(Numeric) && proportion > 0
+          raise ArgumentError, "proportion for #{name} must be a positive number"
+        end
+      end
+    end
+  end
+end

data/lib/yarn_skein/version.rb

@@ -3,6 +3,6 @@
 # :nocov:
 module YarnSkein
   # Current gem version.
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end
 # :nocov:

data/lib/yarn_skein/yardage_estimator.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module YarnSkein
+  # Estimates total yarn yardage required for a project based on gauge and yarn.
+  #
+  # Uses a geometric stitch model: each knit stitch consumes approximately
+  # one stitch-width plus two stitch-heights of yarn (the U-shaped loop path).
+  # This gives a reasonable estimate for stockinette and similar stitch patterns.
+  #
+  # @example
+  #   estimator = YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+  #   estimator.for_rectangle(width: 60.inches, height: 72.inches)
+  #   # => { yardage: <FiberUnits::Length>, skeins: 10 }
+  class YardageEstimator
+    # Default safety margin added to yardage estimates (10%).
+    DEFAULT_MARGIN = 0.10
+
+    # @return [FiberGauge::Gauge] gauge used for stitch/row calculations
+    attr_reader :gauge
+
+    # @return [YarnSkein::Yarn] yarn used for skein calculations
+    attr_reader :yarn
+
+    # @param gauge [FiberGauge::Gauge] gauge swatch data
+    # @param yarn [YarnSkein::Yarn] yarn being used
+    def initialize(gauge:, yarn:)
+      @gauge = gauge
+      @yarn = yarn
+    end
+
+    # Estimates yardage for a rectangular piece (scarf, blanket, etc.).
+    #
+    # @param width [FiberUnits::Length] finished width
+    # @param height [FiberUnits::Length] finished height
+    # @param margin [Float] safety margin as a decimal (default 0.10 = 10%)
+    # @return [Hash] :yardage [FiberUnits::Length] and :skeins [Integer]
+    def for_rectangle(width:, height:, margin: DEFAULT_MARGIN)
+      stitches = gauge.required_stitches(width)
+      rows = gauge.required_rows(height)
+
+      for_piece(stitches: stitches, rows: rows, margin: margin)
+    end
+
+    # Estimates yardage from stitch and row counts directly.
+    #
+    # @param stitches [FiberUnits::StitchCount] total stitches across
+    # @param rows [FiberUnits::RowCount] total rows
+    # @param margin [Float] safety margin as a decimal (default 0.10 = 10%)
+    # @return [Hash] :yardage [FiberUnits::Length] and :skeins [Integer]
+    def for_piece(stitches:, rows:, margin: DEFAULT_MARGIN)
+      total_stitches = stitches.value * rows.value
+      yardage = (total_stitches * yards_per_stitch * (1.0 + margin)).yards
+
+      {yardage: yardage, skeins: yarn.skeins_required(yardage)}
+    end
+
+    # Returns the estimated yards of yarn consumed per stitch.
+    #
+    # Models each stitch as a U-shaped loop: one stitch-width across plus
+    # two stitch-heights for the legs of the loop.
+    #
+    # @return [Float] yards per stitch
+    def yards_per_stitch
+      stitch_width_in = 1.0 / gauge.spi
+      stitch_height_in = 1.0 / gauge.rpi
+      yarn_per_stitch_in = stitch_width_in + (2.0 * stitch_height_in)
+
+      yarn_per_stitch_in / 36.0
+    end
+  end
+end

data/lib/yarn_skein.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require "fiber_units"
+require "fiber_gauge"
 require_relative "yarn_skein/version"
 require_relative "yarn_skein/weight_category"
 require_relative "yarn_skein/fiber_blend"
 require_relative "yarn_skein/yarn"
 require_relative "yarn_skein/substitution"
+require_relative "yarn_skein/yardage_estimator"
+require_relative "yarn_skein/colorwork_estimator"
+require_relative "yarn_skein/catalog"
 
 # Domain objects for describing yarn skeins, fiber blends, and weight classes.
 #

data/test/catalog_test.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "test_helper"
+require "tmpdir"
+require "yaml"
+require "fileutils"
+
+class CatalogTest < Minitest::Test
+  def setup
+    @data_dir = Dir.mktmpdir("catalog_test")
+    write_fixture("malabrigo.yml", {
+      "brand" => "Malabrigo",
+      "slug" => "malabrigo",
+      "yarns" => [
+        {
+          "line" => "Rios",
+          "slug" => "rios",
+          "weight_category" => "worsted",
+          "yardage" => 210,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        },
+        {
+          "line" => "Mechita",
+          "slug" => "mechita",
+          "weight_category" => "fingering",
+          "yardage" => 420,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        }
+      ]
+    })
+
+    write_fixture("cascade.yml", {
+      "brand" => "Cascade",
+      "slug" => "cascade",
+      "yarns" => [
+        {
+          "line" => "220 Superwash",
+          "slug" => "220-superwash",
+          "weight_category" => "worsted",
+          "yardage" => 200,
+          "skein_weight" => 100,
+          "fiber_content" => {"wool" => 100},
+          "colorways" => []
+        }
+      ]
+    })
+
+    # Meta file should be ignored
+    write_fixture("_meta.yml", {"scraped_at" => "2026-01-01", "version" => "1.0"})
+  end
+
+  def teardown
+    FileUtils.rm_rf(@data_dir)
+  end
+
+  # ---- all ----
+
+  def test_all_returns_yarn_objects
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarns = catalog.all
+
+    assert_equal 3, yarns.size
+    assert yarns.all? { |y| y.is_a?(YarnSkein::Yarn) }
+  end
+
+  def test_all_skips_meta_files
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    brands = catalog.all.map(&:brand).uniq
+
+    refute_includes brands, "scraped_at"
+  end
+
+  # ---- filter ----
+
+  def test_filter_by_brand
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(brand: "Malabrigo")
+
+    assert_equal 2, results.size
+    assert results.all? { |y| y.brand == "Malabrigo" }
+  end
+
+  def test_filter_by_weight_category
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(weight_category: :worsted)
+
+    assert_equal 2, results.size
+    assert results.all? { |y| y.weight_category == :worsted }
+  end
+
+  def test_filter_by_fiber
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(fiber: :wool)
+
+    assert_equal 3, results.size
+  end
+
+  def test_filter_combined
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    results = catalog.filter(brand: "Malabrigo", weight_category: :worsted)
+
+    assert_equal 1, results.size
+    assert_equal "Rios", results.first.line
+  end
+
+  # ---- brands ----
+
+  def test_brands_returns_unique_sorted_list
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+
+    assert_equal ["Cascade", "Malabrigo"], catalog.brands
+  end
+
+  # ---- find ----
+
+  def test_find_returns_matching_yarn
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarn = catalog.find(brand: "Malabrigo", line: "Rios")
+
+    assert_equal "Malabrigo", yarn.brand
+    assert_equal "Rios", yarn.line
+  end
+
+  def test_find_is_case_insensitive
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+    yarn = catalog.find(brand: "malabrigo", line: "rios")
+
+    assert_equal "Malabrigo", yarn.brand
+  end
+
+  def test_find_returns_nil_when_not_found
+    catalog = YarnSkein::Catalog.new(data_dir: @data_dir)
+
+    assert_nil catalog.find(brand: "Unknown", line: "Yarn")
+  end
+
+  # ---- empty directory ----
+
+  def test_empty_data_dir
+    empty_dir = Dir.mktmpdir("empty_catalog")
+    catalog = YarnSkein::Catalog.new(data_dir: empty_dir)
+
+    assert_empty catalog.all
+    assert_empty catalog.brands
+  ensure
+    FileUtils.rm_rf(empty_dir)
+  end
+
+  # ---- skips entries without yardage ----
+
+  def test_skips_entries_missing_yardage
+    dir = Dir.mktmpdir("incomplete_catalog")
+    write_fixture_to(dir, "incomplete.yml", {
+      "brand" => "Incomplete",
+      "slug" => "incomplete",
+      "yarns" => [
+        {"line" => "NoYardage", "slug" => "no-yardage", "skein_weight" => 100, "fiber_content" => {}},
+        {"line" => "Valid", "slug" => "valid", "yardage" => 200, "skein_weight" => 100, "fiber_content" => {"wool" => 100}}
+      ]
+    })
+
+    catalog = YarnSkein::Catalog.new(data_dir: dir)
+    assert_equal 1, catalog.all.size
+    assert_equal "Valid", catalog.all.first.line
+  ensure
+    FileUtils.rm_rf(dir)
+  end
+
+  private
+
+  def write_fixture(filename, data)
+    write_fixture_to(@data_dir, filename, data)
+  end
+
+  def write_fixture_to(dir, filename, data)
+    File.write(File.join(dir, filename), YAML.dump(data))
+  end
+end

data/test/colorwork_estimator_test.rb

@@ -0,0 +1,283 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinColorworkEstimatorTest < Minitest::Test
+  def gauge
+    FiberGauge::Gauge.new(
+      stitches: 18.stitches,
+      rows: 24.rows,
+      width: 4.inches,
+      height: 4.inches
+    )
+  end
+
+  def yarn
+    YarnSkein::Yarn.new(
+      brand: "Malabrigo",
+      line: "Rios",
+      yardage: 210.yards,
+      skein_weight: 100.grams
+    )
+  end
+
+  def stranded_estimator
+    YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :stranded)
+  end
+
+  def intarsia_estimator
+    YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :intarsia)
+  end
+
+  # ----------------------------
+  # initialization
+  # ----------------------------
+
+  def test_rejects_invalid_technique
+    assert_raises(ArgumentError) do
+      YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :mosaic)
+    end
+  end
+
+  def test_accepts_stranded_technique
+    est = YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :stranded)
+    assert_equal :stranded, est.technique
+  end
+
+  def test_accepts_intarsia_technique
+    est = YarnSkein::ColorworkEstimator.new(gauge: gauge, technique: :intarsia)
+    assert_equal :intarsia, est.technique
+  end
+
+  # ----------------------------
+  # color validation
+  # ----------------------------
+
+  def test_rejects_empty_colors
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(width: 20.inches, height: 20.inches, colors: {})
+    end
+  end
+
+  def test_rejects_non_hash_colors
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(width: 20.inches, height: 20.inches, colors: [0.5, 0.5])
+    end
+  end
+
+  def test_rejects_proportions_not_summing_to_one
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(
+        width: 20.inches, height: 20.inches,
+        colors: {main: 0.60, contrast: 0.30}
+      )
+    end
+  end
+
+  def test_rejects_zero_proportion
+    assert_raises(ArgumentError) do
+      stranded_estimator.estimate(
+        width: 20.inches, height: 20.inches,
+        colors: {main: 1.0, contrast: 0.0}
+      )
+    end
+  end
+
+  # ----------------------------
+  # stranded estimation
+  # ----------------------------
+
+  def test_stranded_returns_per_color_yardage
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40}
+    )
+
+    assert result.key?(:main)
+    assert result.key?(:contrast)
+    assert result.key?(:total)
+    assert_instance_of FiberUnits::Length, result[:main][:yardage]
+    assert_instance_of FiberUnits::Length, result[:contrast][:yardage]
+    assert_instance_of FiberUnits::Length, result[:total][:yardage]
+  end
+
+  def test_stranded_includes_float_overhead
+    stranded = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.20
+    )
+
+    intarsia = intarsia_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0
+    )
+
+    # Stranded total should be 20% more than intarsia (due to float overhead)
+    stranded_total = stranded[:total][:yardage].to(:yards).value
+    intarsia_total = intarsia[:total][:yardage].to(:yards).value
+
+    assert_in_delta intarsia_total * 1.20, stranded_total, 0.01
+  end
+
+  def test_stranded_custom_float_overhead
+    low_overhead = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.15
+    )
+
+    high_overhead = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      margin: 0.0, float_overhead: 0.25
+    )
+
+    assert high_overhead[:total][:yardage].to(:yards).value >
+           low_overhead[:total][:yardage].to(:yards).value
+  end
+
+  def test_stranded_proportions_affect_distribution
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.70, contrast: 0.30},
+      margin: 0.0
+    )
+
+    main_yards = result[:main][:yardage].to(:yards).value
+    contrast_yards = result[:contrast][:yardage].to(:yards).value
+
+    assert_in_delta 7.0 / 3.0, main_yards / contrast_yards, 0.01
+  end
+
+  # ----------------------------
+  # intarsia estimation
+  # ----------------------------
+
+  def test_intarsia_no_float_overhead
+    intarsia = intarsia_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {left: 0.50, right: 0.50},
+      margin: 0.0
+    )
+
+    # For intarsia, each half should get half the base yardage
+    left_yards = intarsia[:left][:yardage].to(:yards).value
+    right_yards = intarsia[:right][:yardage].to(:yards).value
+
+    assert_in_delta left_yards, right_yards, 0.01
+  end
+
+  def test_intarsia_total_matches_base_yardage
+    intarsia = intarsia_estimator.estimate(
+      width: 20.inches, height: 30.inches,
+      colors: {left: 0.50, right: 0.50},
+      margin: 0.0
+    )
+
+    # Total intarsia yardage should match a plain YardageEstimator (no margin)
+    base = YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+    base_result = base.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+
+    assert_in_delta(
+      base_result[:yardage].to(:yards).value,
+      intarsia[:total][:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # ----------------------------
+  # skein calculations
+  # ----------------------------
+
+  def test_includes_skeins_when_yarn_provided
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      yarn: yarn
+    )
+
+    assert result[:main].key?(:skeins)
+    assert result[:contrast].key?(:skeins)
+    assert_instance_of Integer, result[:main][:skeins]
+    assert_instance_of Integer, result[:contrast][:skeins]
+  end
+
+  def test_omits_skeins_when_no_yarn
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.60, contrast: 0.40}
+    )
+
+    refute result[:main].key?(:skeins)
+    refute result[:contrast].key?(:skeins)
+  end
+
+  # ----------------------------
+  # margin
+  # ----------------------------
+
+  def test_default_margin_applied
+    no_margin = intarsia_estimator.estimate(
+      width: 20.inches, height: 20.inches,
+      colors: {main: 1.0},
+      margin: 0.0
+    )
+
+    with_margin = intarsia_estimator.estimate(
+      width: 20.inches, height: 20.inches,
+      colors: {main: 1.0}
+    )
+
+    assert_in_delta(
+      no_margin[:main][:yardage].to(:yards).value * 1.10,
+      with_margin[:main][:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # ----------------------------
+  # multi-color
+  # ----------------------------
+
+  def test_three_color_stranded
+    result = stranded_estimator.estimate(
+      width: 40.inches, height: 24.inches,
+      colors: {main: 0.50, contrast_a: 0.30, contrast_b: 0.20},
+      margin: 0.0
+    )
+
+    assert result.key?(:main)
+    assert result.key?(:contrast_a)
+    assert result.key?(:contrast_b)
+    assert result.key?(:total)
+
+    total = result[:main][:yardage].to(:yards).value +
+            result[:contrast_a][:yardage].to(:yards).value +
+            result[:contrast_b][:yardage].to(:yards).value
+
+    assert_in_delta total, result[:total][:yardage].to(:yards).value, 0.01
+  end
+
+  # ----------------------------
+  # realistic scenario
+  # ----------------------------
+
+  def test_fair_isle_yoke_estimate_is_reasonable
+    # A Fair Isle yoke ~20" wide, 12" tall in worsted weight
+    result = stranded_estimator.estimate(
+      width: 20.inches, height: 12.inches,
+      colors: {main: 0.60, contrast: 0.40},
+      yarn: yarn
+    )
+
+    main_yards = result[:main][:yardage].to(:yards).value
+    contrast_yards = result[:contrast][:yardage].to(:yards).value
+    total_yards = result[:total][:yardage].to(:yards).value
+
+    assert total_yards > 50, "total #{total_yards} seems too low"
+    assert total_yards < 500, "total #{total_yards} seems too high"
+    assert main_yards > contrast_yards, "main color should use more yarn"
+  end
+end

data/test/yardage_estimator_test.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "test_helper"
+
+class YarnSkeinYardageEstimatorTest < Minitest::Test
+  def gauge
+    FiberGauge::Gauge.new(
+      stitches: 18.stitches,
+      rows: 24.rows,
+      width: 4.inches,
+      height: 4.inches
+    )
+  end
+
+  def yarn
+    YarnSkein::Yarn.new(
+      brand: "Malabrigo",
+      line: "Rios",
+      yardage: 210.yards,
+      skein_weight: 100.grams
+    )
+  end
+
+  def estimator
+    YarnSkein::YardageEstimator.new(gauge: gauge, yarn: yarn)
+  end
+
+  # -----------------------------
+  # yards_per_stitch
+  # -----------------------------
+
+  def test_yards_per_stitch_returns_positive_value
+    assert estimator.yards_per_stitch > 0
+  end
+
+  def test_yards_per_stitch_uses_geometric_model
+    spi = gauge.spi
+    rpi = gauge.rpi
+    expected = (1.0 / spi + 2.0 / rpi) / 36.0
+
+    assert_in_delta expected, estimator.yards_per_stitch, 0.0001
+  end
+
+  # -----------------------------
+  # for_piece
+  # -----------------------------
+
+  def test_for_piece_returns_yardage_and_skeins
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert result.key?(:yardage)
+    assert result.key?(:skeins)
+    assert_instance_of FiberUnits::Length, result[:yardage]
+    assert_instance_of Integer, result[:skeins]
+  end
+
+  def test_for_piece_yardage_is_positive
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert result[:yardage].value > 0
+  end
+
+  def test_for_piece_includes_default_margin
+    no_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+    with_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.10,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_piece_custom_margin
+    no_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+    with_margin = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.20)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.20,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_piece_zero_margin
+    result = estimator.for_piece(stitches: 100.stitches, rows: 100.rows, margin: 0.0)
+
+    total_ops = 100 * 100
+    expected_yards = total_ops * estimator.yards_per_stitch
+
+    assert_in_delta expected_yards, result[:yardage].to(:yards).value, 0.01
+  end
+
+  def test_for_piece_skeins_ceil_to_whole_number
+    result = estimator.for_piece(stitches: 50.stitches, rows: 50.rows, margin: 0.0)
+
+    raw_yards = 50 * 50 * estimator.yards_per_stitch
+    expected_skeins = (raw_yards / 210.0).ceil
+
+    assert_equal expected_skeins, result[:skeins]
+  end
+
+  # -----------------------------
+  # for_rectangle
+  # -----------------------------
+
+  def test_for_rectangle_returns_yardage_and_skeins
+    result = estimator.for_rectangle(width: 20.inches, height: 30.inches)
+
+    assert result.key?(:yardage)
+    assert result.key?(:skeins)
+  end
+
+  def test_for_rectangle_uses_gauge_to_compute_stitches
+    rect_result = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+
+    stitches = gauge.required_stitches(20.inches)
+    rows = gauge.required_rows(30.inches)
+    piece_result = estimator.for_piece(stitches: stitches, rows: rows, margin: 0.0)
+
+    assert_in_delta(
+      piece_result[:yardage].to(:yards).value,
+      rect_result[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  def test_for_rectangle_with_custom_margin
+    no_margin = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.0)
+    with_margin = estimator.for_rectangle(width: 20.inches, height: 30.inches, margin: 0.15)
+
+    assert_in_delta(
+      no_margin[:yardage].to(:yards).value * 1.15,
+      with_margin[:yardage].to(:yards).value,
+      0.01
+    )
+  end
+
+  # -----------------------------
+  # realistic scenarios
+  # -----------------------------
+
+  def test_scarf_estimate_is_reasonable
+    # A scarf ~8" wide, 60" long in worsted weight
+    result = estimator.for_rectangle(width: 8.inches, height: 60.inches)
+
+    yards = result[:yardage].to(:yards).value
+    # A worsted scarf typically uses 200-400 yards
+    assert yards > 100, "yardage #{yards} seems too low for a scarf"
+    assert yards < 600, "yardage #{yards} seems too high for a scarf"
+  end
+
+  def test_blanket_estimate_is_reasonable
+    # A throw blanket ~50" x 60" in worsted weight
+    result = estimator.for_rectangle(width: 50.inches, height: 60.inches)
+
+    yards = result[:yardage].to(:yards).value
+    # A worsted throw typically uses 1500-3500 yards
+    assert yards > 1000, "yardage #{yards} seems too low for a blanket"
+    assert yards < 5000, "yardage #{yards} seems too high for a blanket"
+  end
+
+  def test_larger_piece_needs_more_yarn
+    small = estimator.for_rectangle(width: 10.inches, height: 10.inches)
+    large = estimator.for_rectangle(width: 20.inches, height: 20.inches)
+
+    assert large[:yardage].to(:yards).value > small[:yardage].to(:yards).value
+    assert large[:skeins] >= small[:skeins]
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yarn_skein
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Meagan Waller
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: fiber_gauge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -51,25 +65,31 @@ files:
 - README.md
 - Rakefile
 - lib/yarn_skein.rb
+- lib/yarn_skein/catalog.rb
+- lib/yarn_skein/colorwork_estimator.rb
 - lib/yarn_skein/fiber_blend.rb
 - lib/yarn_skein/substitution.rb
 - lib/yarn_skein/version.rb
 - lib/yarn_skein/weight_category.rb
+- lib/yarn_skein/yardage_estimator.rb
 - lib/yarn_skein/yarn.rb
 - sig/yarn_skein.rbs
+- test/catalog_test.rb
+- test/colorwork_estimator_test.rb
 - test/fiber_blend_test.rb
 - test/substitution_test.rb
 - test/test_helper.rb
 - test/version_test.rb
 - test/weight_category_test.rb
+- test/yardage_estimator_test.rb
 - test/yarn_test.rb
-homepage: https://github.com/meaganewaller/yarn_skein
+homepage: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/meaganewaller/yarn_skein
-  source_code_uri: https://github.com/meaganewaller/yarn_skein
-  changelog_uri: https://github.com/meaganewaller/yarn_skein/blob/main/CHANGELOG.md
+  homepage_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
+  source_code_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein
+  changelog_uri: https://github.com/meaganewaller/craftos/tree/main/gems/yarn_skein/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib