Refactor selector formatting with improved function organization

[bartveneman]

Summary

This PR refactors the selector formatting code to improve clarity and maintainability by breaking down complex functions into smaller, more focused utilities with clear responsibilities and comprehensive documentation.

Key Changes

• Renamed and documented core functions:

  • print_nth() → print_an_plus_b() with JSDoc explaining the An+B microsyntax
  • print_simple_selector() → print_selector_component() to better reflect its role in printing individual selector parts
  • print_inline_selector_list() → print_selector_list() for consistency
  • print_selector_list() (internal) → print_rule_selectors() to distinguish from the exported function

• Extracted specialized formatting functions:

  • print_combinator() - Handles combinator printing ( , >, +, ~, ||) with special logic for descendant combinators
  • print_attribute_selector() - Dedicated function for attribute selector formatting (e.g., [href^="https://" i])
  • print_pseudo_selector() - Handles pseudo-class and pseudo-element formatting with support for functional forms
  • print_selector_argument() - Prints individual items in comma-separated selector positions, handling special forms like :nth-child(2n+1 of .foo)
  • print_selector() - Prints a complete complex selector

• Improved code organization:

  • Moved combinator handling to its own function with clearer logic
  • Separated attribute selector logic into a dedicated function
  • Extracted pseudo-selector formatting with better structure
  • Added comprehensive JSDoc comments explaining each function's purpose and examples

• Updated imports:

  • Added Combinator and AttributeSelector type imports for better type safety

Notable Implementation Details

• The print_combinator() function preserves descendant combinators (whitespace-only) as single spaces even when minifying, preventing selector merging
• The print_pseudo_selector() function handles both legacy pseudo-elements (before, after) and actual pseudo-elements with appropriate double-colon syntax
• The print_selector_argument() function acts as a dispatcher for different selector argument types (nth, nth-of, lang, or regular selectors)
• All formatting functions maintain consistent handling of optional spacing for minification support

https://claude.ai/code/session_01K2xJ3CLyZ8QvobBkwyNG1k

[codecov]

Bundle Report

Changes will increase total bundle size by 1.58kB (8.45%) ⬆️⚠️, exceeding the configured threshold of 5%.

Bundle name	Size	Change
formatCss-esm	17.49kB	1.58kB (9.92%) ⬆️⚠️

Affected Assets, Files, and Routes:

view changes for bundle: formatCss-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
index.js	1.58kB	15.82kB	11.08% ⚠️

Files in index.js:

• ./src/lib/index.ts → Total Size: 15.31kB

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.14%. Comparing base (205b372) to head (897795e).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #225      +/-   ##
==========================================
+ Coverage   97.07%   97.14%   +0.06%     
==========================================
  Files           2        2              
  Lines         376      385       +9     
  Branches      136      137       +1     
==========================================
+ Hits          365      374       +9     
  Misses         10       10              
  Partials        1        1              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.