feat(attribute): Add CanBeSelected, HasLabel traits and selected(), label() methods to manage selected and label attributes for HTML elements.

[terabytesoftw]

Pull Request

Q	A
Is bugfix?	❌
New feature?	✔️
Breaks BC?	❌

[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: 3835a790-849c-458b-89a9-7d8f640194be

📥 Commits

Reviewing files that changed from the base of the PR and between 4960a4f and 436fdc7.

📒 Files selected for processing (8)

• CHANGELOG.md
• src/CanBeSelected.php
• src/HasLabel.php
• src/Values/Attribute.php
• tests/CanBeSelectedTest.php
• tests/HasLabelTest.php
• tests/Provider/LabelProvider.php
• tests/Provider/SelectedProvider.php

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)

• GitHub Check: composer-require-checker / PHP 8.5-ubuntu-latest
• GitHub Check: easy-coding-standard / PHP 8.5-ubuntu-latest
• GitHub Check: mutation / PHP 8.5-ubuntu-latest
• GitHub Check: linter / Super Linter
• GitHub Check: phpunit / PHP 8.5-ubuntu-latest
• GitHub Check: phpunit / PHP 8.2-windows-2022
• GitHub Check: phpunit / PHP 8.4-windows-2022
• GitHub Check: phpunit / PHP 8.2-ubuntu-latest
• GitHub Check: phpunit / PHP 8.3-ubuntu-latest
• GitHub Check: phpunit / PHP 8.1-ubuntu-latest
• GitHub Check: linter / Super Linter

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2026-01-09T16:05:15.502Z

Learnt from: terabytesoftw
Repo: ui-awesome/html-attribute PR: 18
File: tests/Support/Provider/Global/ContentEditableProvider.php:32-33
Timestamp: 2026-01-09T16:05:15.502Z
Learning: Preserve the original copyright year in file headers when moving PHP source files between packages within the ui-awesome repositories (e.g., from ui-awesome/html-core to ui-awesome/html-attribute). Do not update the header year to the current year; keep the original creation year as stated in the header. This applies to all PHP files throughout the repo that are moved between packages.

Applied to files:

• tests/Provider/SelectedProvider.php
• tests/Provider/LabelProvider.php
• src/Values/Attribute.php
• tests/HasLabelTest.php
• tests/CanBeSelectedTest.php
• src/HasLabel.php
• src/CanBeSelected.php

📚 Learning: 2026-02-08T20:05:36.407Z

Learnt from: terabytesoftw
Repo: ui-awesome/html-attribute PR: 80
File: src/HasValue.php:35-35
Timestamp: 2026-02-08T20:05:36.407Z
Learning: In the ui-awesome/html-attribute repository, for methods that accept multiple values of the same type (e.g., boolean true/false), document with a single representative example rather than exhaustively listing all variations. This keeps documentation concise while conveying the intended usage. Apply this consistently across PHP docblocks and examples.

Applied to files:

• tests/Provider/SelectedProvider.php
• tests/Provider/LabelProvider.php
• src/Values/Attribute.php
• tests/HasLabelTest.php
• tests/CanBeSelectedTest.php
• src/HasLabel.php
• src/CanBeSelected.php

📚 Learning: 2026-02-07T13:44:00.931Z

Learnt from: terabytesoftw
Repo: ui-awesome/html-attribute PR: 78
File: tests/Global/HasDirTest.php:92-92
Timestamp: 2026-02-07T13:44:00.931Z
Learning: In PHP test methods that start with testThrowInvalidArgumentException, do not append 'Invalid' again in the method name suffix (e.g., prefer testThrowInvalidArgumentExceptionForSettingDirValue over testThrowInvalidArgumentExceptionForSettingInvalidDirValue). The exception type already communicates invalid input, so the repeated word is redundant. Apply this convention to all similar test methods under the tests/ directory.

Applied to files:

• tests/Provider/SelectedProvider.php
• tests/Provider/LabelProvider.php
• tests/HasLabelTest.php
• tests/CanBeSelectedTest.php

🪛 PHPMD (2.15.0)

tests/HasLabelTest.php

[warning] 68-68: Avoid excessively long variable names like $expectedRenderAttributes. Keep variable name length under 20. (undefined)

(LongVariable)

---

[error] 85-85: Avoid using static access to class '\UIAwesome\Html\Helper\Attributes' in method 'testSetLabelAttributeValue'. (undefined)

(StaticAccess)

tests/CanBeSelectedTest.php

[warning] 66-66: Avoid excessively long variable names like $expectedRenderAttributes. Keep variable name length under 20. (undefined)

(LongVariable)

---

[error] 83-83: Avoid using static access to class '\UIAwesome\Html\Helper\Attributes' in method 'testSetSelectedAttributeValue'. (undefined)

(StaticAccess)

🔇 Additional comments (8)

CHANGELOG.md (1)

61-61: LGTM!

The changelog entry follows the established format and accurately describes the new traits and methods being introduced.

src/HasLabel.php (1)

1-39: LGTM!

The trait implementation is clean and follows the established patterns in the codebase:

• Proper immutable API returning static
• Correct delegation to setAttribute with the Attribute::LABEL enum constant
• Documentation includes representative usage examples and proper MDN link
• Type hints correctly support string|Stringable|UnitEnum|null

tests/Provider/SelectedProvider.php (1)

1-60: LGTM!

The data provider is well-structured with comprehensive test cases covering:

• Boolean true/false states
• null for attribute removal
• Replacement of existing attribute values
• Unsetting via null after a value is set

The PHPStan type annotation accurately reflects the tuple structure.

src/CanBeSelected.php (1)

1-38: LGTM!

The trait implementation follows established patterns:

• Uses the CanBe* naming convention for boolean attributes (consistent with Bug #85 naming changes)
• Proper immutable API with static return type
• Documentation clearly explains true/false/null semantics
• Correct MDN reference for the selected attribute

src/Values/Attribute.php (1)

165-170: LGTM!

The new enum cases are well-integrated:

• LABEL and SELECTED are placed in correct alphabetical order
• Documentation follows the established pattern with attribute description and MDN link
• String values correctly map to HTML attribute names

Also applies to: 277-282

tests/Provider/LabelProvider.php (1)

1-88: LGTM!

The data provider comprehensively covers all supported value types for the label attribute:

• Backed string enum (BackedString::VALUE)
• Unit enum (Unit::value)
• Plain strings
• Stringable instances (via anonymous class)
• null for removal/unsetting

The inline anonymous Stringable class is an elegant approach for testing.

tests/CanBeSelectedTest.php (1)

1-87: LGTM!

The test class provides solid coverage:

• Immutability: testReturnNewInstanceWhenSettingSelectedAttribute correctly verifies that selected() returns a new instance
• Empty state: testReturnEmptyWhenSelectedAttributeNotSet ensures clean initial state
• Data-driven testing: External data provider covers boolean states, null, replacement, and unsetting

Regarding the static analysis hints:

• The $expectedRenderAttributes variable name is appropriately descriptive and consistent with codebase conventions
• Attributes::render is a utility class designed for static access, matching the established pattern throughout the project

tests/HasLabelTest.php (1)

1-89: LGTM!

The test class provides comprehensive coverage and maintains consistency with CanBeSelectedTest:

• Immutability: Correctly verified via assertNotSame
• Empty state: Ensures no attributes are set initially
• Data-driven testing: External data provider covers all value types (string, Stringable, UnitEnum, null)

The static analysis hints regarding variable naming and static access are the same false positives as noted in CanBeSelectedTest—the patterns match established codebase conventions.

---

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added support for managing the selected state of HTML elements through a fluent, immutable interface.
  • Added support for managing labels on HTML elements, supporting multiple value types (strings, enums, etc.) through a fluent, immutable interface.

Walkthrough

This PR introduces two new HTML attribute traits—CanBeSelected and HasLabel—along with corresponding enum constants SELECTED and LABEL to the Attribute enum. The traits provide immutable APIs for managing the selected and label HTML attributes. Test coverage and data providers are included for both traits.

Changes

Cohort / File(s)	Summary
Attribute Traits src/CanBeSelected.php, src/HasLabel.php	New immutable traits providing fluent APIs for setting selected and label attributes via the selected() and label() methods, delegating to setAttribute() internally.
Enum Extension src/Values/Attribute.php	Added two new enum cases: LABEL = 'label' and SELECTED = 'selected' with documentation and MDN links.
Unit Tests tests/CanBeSelectedTest.php, tests/HasLabelTest.php	Test suites validating immutability, empty attribute rendering, and correct attribute setting for both traits using data-driven test methods.
Test Data Providers tests/Provider/SelectedProvider.php, tests/Provider/LabelProvider.php	Data provider classes supplying test cases covering boolean/null values, attribute replacement, and unsetting scenarios.
Documentation CHANGELOG.md	Changelog entry documenting Enh #88 introducing the new traits and methods.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat(attribute): Add HasAs trait and as() method to manage as attribute for HTML elements. #42: Both PRs extend the Attribute enum with new cases while introducing complementary trait-based functionality.
• feat(attribute): Add HasReferrerpolicy trait and referrerpolicy() method to manage referrerpolicy attribute for HTML elements. #38: Both PRs follow the same pattern of adding new attribute-specific traits and corresponding enum cases to the shared Attribute enum.

Suggested labels

enhancement

Poem

🐰 A rabbit hops through HTML fields so bright,
With CanBeSelected and HasLabel in sight,
Now attributes dance to immutable grace,
Traits fluent and clean at a wonderful pace! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: introducing CanBeSelected and HasLabel traits with selected() and label() methods for managing HTML attributes.
Description check	✅ Passed	The description clearly identifies this as a new feature that adds traits and methods for managing selected and label attributes, which directly relates to the changeset.

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

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature_47

---

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.}