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

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 validating adapter-driven :focus-visible and :focus-within behavior and fallbacks when adapters omit focus hooks

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: a6ccb85e-db54-4709-8c8d-e3db9ce09ba9

📥 Commits

Reviewing files that changed from the base of the PR and between 0db63c5 and de23b63.

📒 Files selected for processing (1)

• src/pseudo-selectors/filters.ts

---

📝 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 expanded dynamicStatePseudo union to include isFocusVisible.
Tests test/api.ts	Added tests verifying button:focus-visible when isFocusVisible is provided (and that it matches nothing when omitted) and :focus-within ancestor selection when isFocused is provided (and none when omitted).

Sequence Diagram(s)

mermaid
sequenceDiagram
participant Client as Selector Engine
participant Adapter as Adapter (isFocused / isFocusVisible)
participant DOM as Element Tree
Client->>Adapter: Request state for element (isFocusVisible/isFocused)
Adapter-->>Client: Boolean (or undefined if not implemented)
Client->>DOM: Traverse descendants (via getChildren, isTag) for :focus-within
DOM-->>Client: Child nodes (breadth-first)
Client->>Client: cacheParentResults wraps next; decide match result

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I sniffed the tree for a focused mote,
:focus-within led me down the throat.
:focus-visible twinkles, a subtle light,
Now selectors find the focus just right. ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title accurately describes the main changes: adding support for :focus-visible and :focus-within pseudo-classes.
Linked Issues check	✅ Passed	The PR fully addresses issue #1768 by implementing :focus-visible and :focus-within support through optional adapter methods following the existing dynamic-state pseudo pattern.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing :focus-visible and :focus-within support as required by issue #1768; no out-of-scope changes detected.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{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.