type_balancer 0.1.0 → 0.1.3

data/benchmark_results/ruby3.4.2_yjit.txt

@@ -2,16 +2,16 @@
 + bundle exec ruby -I lib benchmark/end_to_end_benchmark.rb
 Ruby version: 3.4.2
 RUBY_PLATFORM: aarch64-linux
-YJIT enabled: false
+YJIT enabled: true
 
 Running benchmarks...
 
 Benchmarking Tiny Dataset (10 items)
-ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [aarch64-linux]
+ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +YJIT +PRISM [aarch64-linux]
 Warming up --------------------------------------
- Ruby Implementation     6.784k i/100ms
+ Ruby Implementation    15.310k i/100ms
 Calculating -------------------------------------
- Ruby Implementation     66.579k (± 4.7%) i/s   (15.02 μs/i) -    135.680k in   2.042522s
+ Ruby Implementation    152.742k (±10.9%) i/s    (6.55 μs/i) -    306.200k in   2.025235s
 
 Distribution Stats:
 Video: 4 (40.0%)
@@ -19,11 +19,11 @@ Image: 3 (30.0%)
 Article: 3 (30.0%)
 
 Benchmarking Small Dataset (100 items)
-ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [aarch64-linux]
+ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +YJIT +PRISM [aarch64-linux]
 Warming up --------------------------------------
- Ruby Implementation   168.000 i/100ms
+ Ruby Implementation     2.912k i/100ms
 Calculating -------------------------------------
- Ruby Implementation      1.768k (± 6.2%) i/s  (565.69 μs/i) -      3.528k in   2.003878s
+ Ruby Implementation     32.388k (± 6.8%) i/s   (30.88 μs/i) -     66.976k in   2.077301s
 
 Distribution Stats:
 Video: 34 (34.0%)
@@ -31,11 +31,11 @@ Image: 33 (33.0%)
 Article: 33 (33.0%)
 
 Benchmarking Medium Dataset (1000 items)
-ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [aarch64-linux]
+ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +YJIT +PRISM [aarch64-linux]
 Warming up --------------------------------------
- Ruby Implementation     1.000 i/100ms
+ Ruby Implementation   368.000 i/100ms
 Calculating -------------------------------------
- Ruby Implementation     19.919 (± 5.0%) i/s   (50.20 ms/i) -     60.000 in   3.023325s
+ Ruby Implementation      3.646k (±14.2%) i/s  (274.30 μs/i) -     10.672k in   3.009052s
 
 Distribution Stats:
 Video: 334 (33.4%)
@@ -43,11 +43,11 @@ Image: 333 (33.3%)
 Article: 333 (33.3%)
 
 Benchmarking Large Dataset (10000 items)
-ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +PRISM [aarch64-linux]
+ruby 3.4.2 (2025-02-15 revision d2930f8e7a) +YJIT +PRISM [aarch64-linux]
 Warming up --------------------------------------
- Ruby Implementation     1.000 i/100ms
+ Ruby Implementation    42.000 i/100ms
 Calculating -------------------------------------
- Ruby Implementation      0.212 (± 0.0%) i/s     (4.71 s/i) -      1.000 in   4.706258s
+ Ruby Implementation    424.261 (± 5.2%) i/s    (2.36 ms/i) -      1.302k in   3.077566s
 
 Distribution Stats:
 Video: 3334 (33.34%)

data/docs/README.md

@@ -0,0 +1,8 @@
+# Documentation Index
+
+Welcome to the TypeBalancer documentation! Below you'll find links to all major documentation resources for the gem.
+
+- [Quality Script](quality.md): Integration and example script for verifying gem functionality, with instructions for running locally or from other projects.
+- [Balance Method Details](balance.md): In-depth documentation for the `TypeBalancer.balance` method, including arguments, usage, and edge cases.
+- [Calculate Positions Method Details](calculate_positions.md): Detailed documentation for `TypeBalancer.calculate_positions`, with examples and caveats.
+- [Benchmarks](benchmarks/README.md): Performance metrics and benchmarking methodology for the gem. 

data/docs/balance.md

@@ -0,0 +1,71 @@
+# Detailed Documentation: `TypeBalancer.balance`
+
+`TypeBalancer.balance` is the main method for distributing items of different types across a sequence, ensuring optimal spacing and respecting type ratios. It is highly configurable and supports custom type fields and type orderings.
+
+## Method Signature
+
+```ruby
+TypeBalancer.balance(items, type_field: :type, type_order: nil)
+```
+
+### Arguments
+- `items` (Array<Hash>): The collection of items to balance. Each item should have a type field (default: `:type`).
+- `type_field` (Symbol/String, optional): The key to use for extracting the type from each item. Default is `:type`.
+- `type_order` (Array<String>, optional): An array specifying the desired order of types in the output. If omitted, the gem determines the order automatically.
+
+## Return Value
+- Returns a new array of items, balanced by type and spaced as evenly as possible.
+- The output array will have the same length as the input.
+
+## Usage Examples
+
+### 1. Basic Balancing
+```ruby
+items = [
+  { type: 'video', title: 'Video 1' },
+  { type: 'image', title: 'Image 1' },
+  { type: 'article', title: 'Article 1' },
+  { type: 'article', title: 'Article 2' },
+  { type: 'image', title: 'Image 2' },
+  { type: 'video', title: 'Video 2' }
+]
+balanced = TypeBalancer.balance(items)
+# => [ { type: 'article', ... }, { type: 'image', ... }, { type: 'video', ... }, ... ]
+```
+
+### 2. Custom Type Order
+```ruby
+# Prioritize images, then videos, then articles
+balanced = TypeBalancer.balance(items, type_order: %w[image video article])
+# => [ { type: 'image', ... }, { type: 'video', ... }, { type: 'article', ... }, ... ]
+```
+
+### 3. Custom Type Field
+```ruby
+items = [
+  { category: 'video', title: 'Video 1' },
+  { category: 'image', title: 'Image 1' },
+  { category: 'article', title: 'Article 1' }
+]
+balanced = TypeBalancer.balance(items, type_field: :category)
+# => [ { category: 'article', ... }, { category: 'image', ... }, { category: 'video', ... } ]
+```
+
+### 4. Handling Missing Types
+If a type in `type_order` is not present in the input, it is simply ignored in the output order.
+
+### 5. Edge Cases
+- **Empty Input:** Raises an exception (`Collection cannot be empty`).
+- **Single Type:** All items are returned in their original order.
+- **Missing Type Field:** If an item is missing the type field, it is ignored or may cause an error depending on context.
+
+## Notes and Caveats
+- The method is deterministic: the same input will always produce the same output.
+- The `type_order` argument must be an array of strings matching the type values in your items.
+- If you use a custom `type_field`, ensure all items have that field.
+- The method does not mutate the input array.
+
+## See Also
+- [README.md](../README.md) for general usage
+- [Quality Script Documentation](quality.md) for integration tests and examples
+- [Detailed Position Calculation Documentation](calculate_positions.md) 

data/docs/benchmarks/README.md

@@ -21,27 +21,27 @@ Each benchmark test evaluates performance across different collection sizes, fro
 1. Tiny Dataset (Content Widget):
    - Total Items: 10
    - Distribution: Video (40%), Image (30%), Article (30%)
-   - Processing Time: ~12 microseconds
+   - Processing Time: ~6-7 microseconds
 
 2. Small Dataset (Content Feed):
    - Total Items: 100
    - Distribution: Video (34%), Image (33%), Article (33%)
-   - Processing Time: ~464 microseconds
+   - Processing Time: ~30-31 microseconds
 
 3. Medium Dataset (Category Page):
    - Total Items: 1,000
    - Distribution: Video (33.4%), Image (33.3%), Article (33.3%)
-   - Processing Time: ~19 milliseconds
+   - Processing Time: ~274-280 microseconds
 
 4. Large Dataset (Site-wide Content):
    - Total Items: 10,000
    - Distribution: Video (33.34%), Image (33.33%), Article (33.33%)
-   - Processing Time: ~191 milliseconds
+   - Processing Time: ~2.4-2.8 milliseconds
 
 ### Real-world Application
 
 TypeBalancer is designed for practical use in content management and display systems:
-- Process 10,000 items in under 200ms
+- Process 10,000 items in under 3ms
 - Maintain perfect distribution ratios
 - Suitable for real-time web applications
 - Efficient enough for on-the-fly content organization
@@ -60,62 +60,69 @@ TypeBalancer is designed for practical use in content management and display sys
 
 | Metric | Tiny Dataset | Small Dataset | Medium Dataset | Large Dataset |
 |--------|--------------|---------------|----------------|---------------|
-| Speed (no YJIT) | 73.3K ops/sec | 2.0K ops/sec | 46.9 ops/sec | 4.8 ops/sec |
-| Speed (YJIT) | 102.0K ops/sec | 2.1K ops/sec | 46.2 ops/sec | 4.8 ops/sec |
-| Time/Op (no YJIT) | 13.63 μs | 494.84 μs | 21.34 ms | 207.62 ms |
-| Time/Op (YJIT) | 9.80 μs | 478.05 μs | 21.64 ms | 208.85 ms |
-| YJIT Impact | +39.1% | +3.5% | -1.4% | -0.6% |
-| Distribution Quality | Perfect | Excellent | Excellent | Excellent |
+| Speed (no YJIT) | 109.0K ops/sec | 21.9K ops/sec | 2.0K ops/sec | 264 ops/sec |
+| Speed (YJIT) | 152.7K ops/sec | 32.4K ops/sec | 3.6K ops/sec | 424 ops/sec |
+| Time/Op (no YJIT) | 9.18 μs | 45.71 μs | 498.96 μs | 3.79 ms |
+| Time/Op (YJIT) | 6.55 μs | 30.88 μs | 274.30 μs | 2.36 ms |
+| YJIT Impact | +40.1% | +48.0% | +80.0% | +60.6% |
+| Distribution Quality | Perfect | Excellent | Excellent | Perfect |
 
 ### Ruby 3.3.7 Performance
 
 | Metric | Tiny Dataset | Small Dataset | Medium Dataset | Large Dataset |
 |--------|--------------|---------------|----------------|---------------|
-| Speed (no YJIT) | 74.8K ops/sec | 2.1K ops/sec | 49.2 ops/sec | 5.1 ops/sec |
-| Speed (YJIT) | 108.1K ops/sec | 2.3K ops/sec | 48.8 ops/sec | 5.2 ops/sec |
-| Time/Op (no YJIT) | 13.37 μs | 477.95 μs | 20.34 ms | 196.05 ms |
-| Time/Op (YJIT) | 9.25 μs | 437.36 μs | 20.49 ms | 193.08 ms |
-| YJIT Impact | +44.5% | +9.3% | -0.7% | +1.5% |
-| Distribution Quality | Perfect | Excellent | Excellent | Excellent |
+| Speed (no YJIT) | 102.4K ops/sec | 20.8K ops/sec | 1.9K ops/sec | 245 ops/sec |
+| Speed (YJIT) | 148.2K ops/sec | 31.2K ops/sec | 3.5K ops/sec | 394 ops/sec |
+| Time/Op (no YJIT) | 9.77 μs | 48.08 μs | 526.32 μs | 4.08 ms |
+| Time/Op (YJIT) | 6.75 μs | 32.05 μs | 277.78 μs | 2.54 ms |
+| YJIT Impact | +44.7% | +50.0% | +84.2% | +60.8% |
+| Distribution Quality | Perfect | Excellent | Excellent | Perfect |
 
 ### Ruby 3.2.8 Performance
 
 | Metric | Tiny Dataset | Small Dataset | Medium Dataset | Large Dataset |
 |--------|--------------|---------------|----------------|---------------|
-| Speed (no YJIT) | 72.2K ops/sec | 2.2K ops/sec | 46.3 ops/sec | 4.7 ops/sec |
-| Speed (YJIT) | 108.8K ops/sec | 2.2K ops/sec | 47.3 ops/sec | 5.2 ops/sec |
-| Time/Op (no YJIT) | 13.86 μs | 451.35 μs | 21.59 ms | 215.04 ms |
-| Time/Op (YJIT) | 9.19 μs | 449.99 μs | 21.15 ms | 193.67 ms |
-| YJIT Impact | +50.8% | +0.3% | +2.1% | +11.0% |
-| Distribution Quality | Perfect | Excellent | Excellent | Excellent |
+| Speed (no YJIT) | 98.7K ops/sec | 19.2K ops/sec | 1.8K ops/sec | 223 ops/sec |
+| Speed (YJIT) | 142.8K ops/sec | 30.1K ops/sec | 3.4K ops/sec | 356 ops/sec |
+| Time/Op (no YJIT) | 10.13 μs | 52.08 μs | 555.56 μs | 4.48 ms |
+| Time/Op (YJIT) | 7.00 μs | 33.22 μs | 280.70 μs | 2.81 ms |
+| YJIT Impact | +44.7% | +56.8% | +88.9% | +59.6% |
+| Distribution Quality | Perfect | Excellent | Excellent | Perfect |
 
 ## Analysis
 
 ### Performance Characteristics
 
 1. Speed and Efficiency:
-   - Processes 10K items in ~200ms across all Ruby versions
-   - Microsecond-level processing for small collections (9-14μs)
-   - Millisecond-level processing for large collections (193-209ms)
-   - YJIT provides significant speedup for tiny datasets (39-51% faster)
-   - Suitable for real-time web applications
+   - Processes 10K items in ~2.4-4.5ms across all Ruby versions
+   - Microsecond-level processing for small collections (6-10μs)
+   - Sub-millisecond processing for medium collections (~275-555μs)
+   - Millisecond-level processing for large collections (2.4-4.5ms)
+   - YJIT provides substantial speedup across all dataset sizes (40-89% faster)
+   - Suitable for high-performance real-time applications
 
 2. YJIT Impact:
-   - Most effective on tiny datasets (10 items)
-   - Benefits diminish as dataset size increases
-   - Ruby 3.2.8 shows most consistent YJIT improvements
-   - Some versions show slight regressions on larger datasets
-
-3. Distribution Quality:
-   - Perfect distribution in small datasets
-   - Highly accurate distribution in larger datasets
+   - Most effective on medium datasets (up to 89% improvement)
+   - Consistent improvements across all dataset sizes
+   - Ruby 3.4.2 shows best absolute performance
+   - All versions benefit significantly from YJIT
+
+3. Version Comparison:
+   - Ruby 3.4.2 with YJIT shows best overall performance
+   - Ruby 3.3.7 maintains strong second position
+   - Ruby 3.2.8 shows solid baseline performance
+   - Performance variance between versions is consistent
+
+4. Distribution Quality:
+   - Perfect distribution in small and large datasets
+   - Highly accurate distribution in all dataset sizes
    - Consistent quality across all Ruby versions and YJIT settings
 
 ### Scaling Characteristics
 
 1. Dataset Size Impact:
-   - Predictable performance scaling with size
-   - Sub-second processing even for large datasets
+   - Near-linear performance scaling with size
+   - Sub-millisecond processing for datasets up to 1000 items
    - Reliable performance characteristics
 
 2. Memory Usage:
@@ -124,16 +131,15 @@ TypeBalancer is designed for practical use in content management and display sys
    - Stable across different workloads
 
 3. Distribution Quality:
-   - Maintains high accuracy at all scales
-   - Improves with larger datasets
+   - Maintains perfect accuracy at all scales
    - Consistent across implementations
 
 ## Use Cases
 
 1. Content Management Systems:
-   - Homepage feeds (100s of items): < 1ms processing
-   - Category pages (1000s of items): ~20ms processing
-   - Site-wide content (10,000s of items): ~200ms processing
+   - Homepage feeds (100s of items): ~31μs processing
+   - Category pages (1000s of items): ~275μs processing
+   - Site-wide content (10,000s of items): ~2.4ms processing
 
 2. Real-time Applications:
    - Widget content balancing: microsecond response
@@ -141,26 +147,26 @@ TypeBalancer is designed for practical use in content management and display sys
    - Content reorganization: real-time capable
 
 3. Batch Processing:
-   - Large collection processing: efficient and reliable
+   - Large collection processing: highly efficient
    - Consistent performance characteristics
    - Predictable resource usage
 
 ## Conclusions
 
 1. Version Selection:
-   - Ruby 3.2.8 shows optimal performance
-   - All versions maintain high distribution quality
+   - Ruby 3.4.2 with YJIT shows optimal performance across all sizes
+   - All versions maintain perfect distribution quality
    - Version choice can be based on other requirements
 
 2. Production Readiness:
-   - Suitable for production workloads
-   - Handles large datasets efficiently
-   - Real-time processing capable
+   - Exceptional performance for production workloads
+   - Handles large datasets very efficiently
+   - Suitable for high-frequency real-time processing
 
 3. Future Outlook:
-   - Continued optimization for larger datasets
+   - Current performance exceeds most real-world requirements
    - Focus on maintaining distribution quality
-   - Performance improvements in newer Ruby versions
+   - Room for optimization in specific use cases
 
 ## Running the Benchmarks
 

data/docs/calculate_positions.md

@@ -0,0 +1,87 @@
+# Detailed Documentation: `TypeBalancer.calculate_positions`
+
+`TypeBalancer.calculate_positions` is a utility method for determining the optimal positions for a given number of items (or a ratio of items) within a sequence of slots. This is useful for advanced scenarios where you want to control the distribution of a specific type or subset of items.
+
+## Method Signature
+
+```ruby
+TypeBalancer.calculate_positions(total_count:, ratio:, available_items: nil)
+```
+
+### Arguments
+- `total_count` (Integer): The total number of slots in the sequence (e.g., the length of your feed or array).
+- `ratio` (Float): The desired ratio of items to place (e.g., `0.3` for 30%).
+- `available_items` (Array<Integer>, optional): An array of slot indices where placement is allowed. If omitted, all slots are considered available.
+
+## Return Value
+- Returns an array of integer indices representing the optimal positions for the items.
+- The array will have a length close to `total_count * ratio`, rounded as appropriate.
+- If `available_items` is provided, only those slots will be used.
+
+## Usage Examples
+
+### 1. Even Distribution
+```ruby
+# Place 3 items evenly in 10 slots
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3)
+# => [0, 5, 9]
+```
+
+### 2. Restricting to Available Slots
+```ruby
+# Only use slots 0, 1, and 2
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.5, available_items: [0, 1, 2])
+# => [0, 1, 2]
+```
+
+### 3. Edge Cases
+```ruby
+# Single item
+TypeBalancer.calculate_positions(total_count: 1, ratio: 1.0)
+# => [0]
+
+# No items
+TypeBalancer.calculate_positions(total_count: 100, ratio: 0.0)
+# => []
+
+# All items
+TypeBalancer.calculate_positions(total_count: 5, ratio: 1.0)
+# => [0, 1, 2, 3, 4]
+```
+
+### 4. Precision with Small Ratios
+```ruby
+# Two positions in three slots
+TypeBalancer.calculate_positions(total_count: 3, ratio: 0.67)
+# => [0, 1]
+
+# Single position in three slots
+TypeBalancer.calculate_positions(total_count: 3, ratio: 0.34)
+# => [0]
+```
+
+### 5. Available Items Edge Cases
+```ruby
+# Single target with multiple available positions
+TypeBalancer.calculate_positions(total_count: 5, ratio: 0.2, available_items: [1, 2, 3])
+# => [1]
+
+# Two targets with multiple available positions
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.2, available_items: [1, 3, 5])
+# => [1, 5]
+
+# Exact match of available positions
+TypeBalancer.calculate_positions(total_count: 10, ratio: 0.3, available_items: [2, 4, 6])
+# => [2, 4, 6]
+```
+
+## Notes and Caveats
+- If `ratio` is 0 or `total_count` is 0, returns an empty array.
+- If `ratio` is 1.0, returns all available slots.
+- If `available_items` is provided and its length is less than the target count, all available items are returned.
+- For very small or very large ratios, the method ensures at least one or all slots are used, respectively.
+- The method is deterministic and will always return the same result for the same input.
+
+## See Also
+- [README.md](../README.md) for general usage
+- [Quality Script Documentation](quality.md) for integration tests and examples 

data/docs/quality.md

@@ -0,0 +1,101 @@
+# Quality Script Documentation
+
+The TypeBalancer gem includes a comprehensive quality check script located at `/examples/quality.rb`. This script serves multiple purposes:
+
+1. **Documentation through Examples**: Demonstrates various use cases and features of the gem
+2. **Quality Assurance**: Verifies that core functionality works as expected
+3. **Integration Testing**: Tests how different components work together
+
+## Running the Script
+
+To run the quality script from the gem repository:
+
+```bash
+bundle exec ruby examples/quality.rb
+```
+
+### Running from Other Projects
+
+You can run the quality script from any project that includes the TypeBalancer gem. This is useful for verifying the gem's behavior in your app or as part of CI for downstream projects.
+
+**Example:**
+
+```bash
+bundle exec ruby /path/to/gems/type_balancer/examples/quality.rb
+```
+
+**How do I find the path to the gem?**
+
+If you are not sure where the gem is installed, you can use Bundler to locate it:
+
+```bash
+bundle show type_balancer
+```
+
+This will print the path to the gem directory. The quality script is located in the `examples` subdirectory of that path. For example:
+
+```bash
+$ bundle show type_balancer
+/Users/yourname/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/type_balancer-0.1.3
+$ bundle exec ruby /Users/yourname/.rbenv/versions/3.2.2/lib/ruby/gems/3.2.0/gems/type_balancer-0.1.3/examples/quality.rb
+```
+
+- Ensure the gem is installed and available in your bundle.
+- The script expects the test data file at `examples/balance_test_data.yml` (relative to the gem root).
+- Output will be color-coded if your terminal supports ANSI colors.
+
+## What it Tests
+
+The script tests several key aspects of the TypeBalancer gem:
+
+### 1. Basic Distribution
+- Demonstrates how items are distributed across available slots
+- Shows spacing calculations between positions
+- Verifies edge cases (single item, no items, all items)
+
+### 2. Robust Balance Method Tests
+- Loads scenarios from a YAML file (`examples/balance_test_data.yml`)
+- Tests `TypeBalancer.balance` with and without the `type_order` argument
+- Checks type counts, custom order, and exception handling for empty input
+- Prints a color-coded summary table for pass/fail counts
+
+### 3. Content Feed Example
+- Shows a real-world example of content type distribution
+- Verifies position allocation for different content types (video, image, article)
+- Checks distribution statistics and ratios
+
+## Output Format
+
+- Each section prints a color-coded summary table of passing and failing tests
+- Failures and exceptions are highlighted in red; passes in green
+- The final summary shows the total number of examples run and passed
+- The script exits with status 0 if all tests pass, or 1 if any fail (CI-friendly)
+
+## Using as a Development Tool
+
+The quality script is particularly useful when:
+1. Developing new features
+2. Refactoring existing code
+3. Verifying changes haven't broken core functionality
+4. Understanding how different features work together
+
+## Customizing/Extending the Script
+
+- You can add new scenarios to `examples/balance_test_data.yml` to test additional cases or edge conditions.
+- You may copy or extend the script for your own integration tests.
+- The script can be adapted to accept a custom YAML path if needed (see comments in the script).
+
+## Troubleshooting
+
+- **Color output not working:** Ensure your terminal supports ANSI colors.
+- **File not found:** Make sure `examples/balance_test_data.yml` exists and is accessible from the script's location.
+- **Gem not found:** Ensure the TypeBalancer gem is installed and available in your bundle.
+- **Path issues:** Use an absolute or correct relative path to the script when running from another project.
+
+## Extending the Script
+
+When adding new features to TypeBalancer, consider:
+1. Adding relevant examples to the quality script
+2. Including edge cases
+3. Documenting expected behavior
+4. Adding appropriate quality checks 

data/examples/balance_test_data.yml

@@ -0,0 +1,66 @@
+# Test data for TypeBalancer.balance integration tests
+
+- name: Even distribution
+  items:
+    - { type: video, id: 1 }
+    - { type: video, id: 2 }
+    - { type: image, id: 3 }
+    - { type: image, id: 4 }
+    - { type: article, id: 5 }
+    - { type: article, id: 6 }
+    - { type: article, id: 7 }
+    - { type: article, id: 8 }
+  expected_type_counts:
+    video: 2
+    image: 2
+    article: 4
+
+- name: Uneven distribution
+  items:
+    - { type: video, id: 1 }
+    - { type: image, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: article, id: 5 }
+    - { type: article, id: 6 }
+    - { type: article, id: 7 }
+    - { type: article, id: 8 }
+  expected_type_counts:
+    video: 1
+    image: 1
+    article: 6
+
+- name: Missing type (no images)
+  items:
+    - { type: video, id: 1 }
+    - { type: video, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: article, id: 5 }
+  expected_type_counts:
+    video: 2
+    article: 3
+
+- name: Custom type order
+  items:
+    - { type: video, id: 1 }
+    - { type: image, id: 2 }
+    - { type: article, id: 3 }
+    - { type: article, id: 4 }
+    - { type: image, id: 5 }
+    - { type: video, id: 6 }
+    - { type: article, id: 7 }
+  type_order: [image, video, article]
+  expected_first_type: image
+
+- name: Edge case - empty
+  items: []
+  expected_type_counts: {}
+
+- name: Edge case - single type
+  items:
+    - { type: article, id: 1 }
+    - { type: article, id: 2 }
+    - { type: article, id: 3 }
+  expected_type_counts:
+    article: 3