feat: add :focus-visible and :focus-within support

[RedZapdos123]

Description:

• Add :focus-visible support via an optional adapter isFocusVisible method.
• Add :focus-within support via an optional adapter isFocused method.
• Extend adapter typings for isFocused and isFocusVisible.
• Add regression tests for both selectors and fallback behavior when adapter methods are missing.
• Document the new pseudo-classes in the README.

Verification:

• npm run test:vi
• npm run build
• runtime probe confirms :focus-visible and :focus-within now compile and match

Resolves #1768

The validation screenshot of the tests run, locally:

Summary by CodeRabbit

• New Features

  • Support added for :focus-visible and :focus-within pseudo-selectors

• Documentation

  • Updated supported selectors list to include :focus-visible and :focus-within with MDN links

• Tests

  • Added tests verifying :focus-visible and :focus-within behavior and fallbacks when focus-related hooks are not provided

[coderabbitai]

📝 Walkthrough

Walkthrough

Added support for two focus-related pseudo-classes—:focus-visible and :focus-within—by extending the adapter API with focus predicates, implementing selector logic (including descendant traversal for :focus-within), updating filters, adding tests, and documenting the selectors.

Changes

Cohort / File(s)	Summary
Documentation README.md	Added :focus-visible and :focus-within to the supported selectors list with MDN links and comma-separated formatting.
Type Definitions src/types.ts	Extended Adapter<Node, ElementNode> with optional methods isFocused?: (element: ElementNode) => boolean and isFocusVisible?: (element: ElementNode) => boolean.
Filter Implementation src/pseudo-selectors/filters.ts	Added "focus-visible" mapped to dynamicStatePseudo("isFocusVisible") and implemented "focus-within" via a new focusWithinPseudo that uses adapter.isFocused plus breadth-first descendant traversal (respecting adapter.isTag) and cacheParentResults. Also extended dynamicStatePseudo accepted method names to include isFocusVisible.
Tests test/api.ts	Added tests verifying button:focus-visible when isFocusVisible is provided (and no matches when omitted) and :focus-within ancestor selection when isFocused is provided (and none when omitted).

Sequence Diagram(s)

sequenceDiagram
    participant Engine as Selector Engine
    participant Adapter as Adapter (isFocused / isFocusVisible)
    participant DOM as Element Tree
    Engine->>Adapter: query isFocusVisible(element)?
    Adapter-->>Engine: true / false / undefined
    Engine->>DOM: if :focus-within -> getChildren(node)
    DOM-->>Engine: child nodes (breadth-first)
    Engine->>Adapter: query isFocused(descendant)?
    Adapter-->>Engine: true / false / undefined
    Engine->>Engine: cacheParentResults(next) -> mark ancestor matches

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I sniffed the branch where focus might hide,
:focus-within led me down inside.
:focus-visible blinked soft and bright,
Now selectors hop to the focused light. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding support for two new CSS pseudo-classes to the library.
Linked Issues check	✅ Passed	The PR fully addresses issue #1768 by implementing :focus-visible and :focus-within support following the existing dynamic-state pseudo-class pattern with optional adapter methods.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the two pseudo-classes: type definitions, filters implementation, tests, and documentation updates align with issue #1768 requirements.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

@RedZapdos123 Thanks for adding the docstring for focusWithinPseudo and confirming the validation steps passed! I'll kick off a new review of the PR now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[RedZapdos123]

Added the missing docstring for focusWithinPseudo in src/pseudo-selectors/filters.ts to address Docstring Coverage.

Validation ReRun:

• npm run test:vi
• npm run build

@coderabbitai review

[coderabbitai]

@RedZapdos123 Thanks for adding the docstring for focusWithinPseudo and confirming the validation steps passed! I'll kick off a new review of the PR now.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[RedZapdos123]

I feel the current code changes in the commit are fine, and the CodeRabbit is just being too nitpicky.

I have resolved all of the code review comments by CodeRabbit.