fix(docs): Update documentation traits and enums for clarity and consistency.

[terabytesoftw]

Pull Request

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

Summary by CodeRabbit

• Documentation

  • Streamlined and clarified attribute, global property, and enum docs to focus on practical API usage and examples.

• Chores

  • Locked a dependency version for more predictable compatibility.

• Bug Fixes

  • Added CHANGELOG entry for Bug fix(docs): Update documentation traits and enums for clarity and consistency. #24 to document clarity improvements in attribute-related documentation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors many PHP docblocks across traits and enums to remove "standards-compliant" wording and simplify descriptions; updates one exception message string quoting; tightens a composer dependency version; and adds a changelog entry for Bug #24.

Changes

Cohort / File(s)	Summary
Configuration Updates composer.json	Change ui-awesome/html-mixin requirement from ^0.4@dev to ^0.3.
Changelog CHANGELOG.md	Add entry documenting Bug #24 about documentation trait and enum clarity updates.
Exception Message Enum src/Exception/Message.php	Adjust ATTRIBUTE_INVALID_VALUE case template to use single quotes around placeholders.
Element Traits (Documentation) src/Element/HasAlt.php, src/Element/HasDecoding.php, src/Element/HasHeight.php, src/Element/HasHref.php, src/Element/HasReferrerpolicy.php, src/Element/HasSrc.php, src/Element/HasWidth.php	Simplify docblocks: remove "standards-compliant" language, trim usage examples, adjust @link placements; no signature or behavior changes.
Global Traits (Documentation) src/Global/CanBeAutofocus.php, src/Global/CanBeHidden.php, src/Global/HasAccesskey.php, src/Global/HasAria.php, src/Global/HasClass.php, src/Global/HasContentEditable.php, src/Global/HasData.php, src/Global/HasDir.php, src/Global/HasDraggable.php, src/Global/HasEvents.php, src/Global/HasId.php, src/Global/HasLang.php, src/Global/HasMicroData.php, src/Global/HasRole.php, src/Global/HasSpellcheck.php, src/Global/HasStyle.php, src/Global/HasTabindex.php, src/Global/HasTitle.php, src/Global/HasTranslate.php	Reword docblocks to generic "immutable API" phrasing, remove or shorten examples, adjust link formatting; no code/signature changes.
Additional Traits (Documentation) src/HasCrossorigin.php, src/HasFetchpriority.php, src/HasRel.php	Docblock wording simplifications and example/link edits; behavior unchanged.
Value Enums (Documentation) src/Values/Aria.php, src/Values/Attribute.php, src/Values/ContentEditable.php, src/Values/Crossorigin.php, src/Values/Data.php, src/Values/Decoding.php, src/Values/Direction.php, src/Values/Draggable.php, src/Values/ElementAttribute.php, src/Values/Event.php, src/Values/Fetchpriority.php, src/Values/GlobalAttribute.php, src/Values/Language.php, src/Values/Referrerpolicy.php, src/Values/Rel.php, src/Values/Role.php, src/Values/Translate.php	Update PHPDoc to remove "standardized" terminology, reframe enums as curated token sets, add notes that enum values map to string tokens; no enum case or signature changes.

Sequence Diagram(s)

(Skipped — changes are documentation, a dependency constraint, and a single-string edit; no new multi-component control flow to visualize.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• fix(docs): Update documentation for Crossorigin and ElementAttribute enums to clarify attribute representation and compliance with MDN standards. #22: Documentation refactors affecting ElementAttribute and Crossorigin — overlaps docblock edits in this PR.
• feat(attribute): Add HasFetchpriority trait and fetchpriority() method to manage fetchpriority attribute for HTML/SVG elements. #21: Adds or modifies HasFetchpriority / Fetchpriority — related to this PR's docs for the same trait/enum.

Poem

🐰 Notes trimmed, docblocks neat and light,
I hopped through comments in the night.
Quotes switched, constraints made precise,
A tidy changelog, small but nice.
Hop, patch, commit — I’m feeling bright! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 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 summarizes the main change: updating documentation in traits and enums for clarity and consistency, which aligns with the primary focus of the changeset across 40+ files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing touches

• 📝 Generate docstrings

---

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]

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/Global/HasData.php (1)

78-83: Align supported-types wording with actual signature.

The sentence “supporting both string and Closure” understates what’s supported (scalar, Stringable, UnitEnum, etc.). Consider broadening the wording to match the signature.

💡 Suggested doc tweak

- * Creates a new instance with the specified custom data attributes, supporting both string and Closure as required
- * by the HTML specification for global attributes, and throws an exception for invalid input.
+ * Creates a new instance with the specified custom data attributes, supporting scalar, Stringable, UnitEnum,
+ * Closure, and null values, and throws an exception for invalid input.

🤖 Fix all issues with AI agents

In `@src/Global/HasAccesskey.php`:
- Line 18: Update the class/trait docblock in HasAccesskey (the comment that
starts with "Handles the HTML `accesskey` global attributes") to use the
singular form "attribute" instead of "attributes" so it reads "Handles the HTML
`accesskey` global attribute", matching the style of other traits like
CanBeHidden.

In `@src/Global/HasTitle.php`:
- Line 20: Update the docblock comment in the HasTitle trait to use the singular
word "attribute" instead of "attributes" for consistency with other traits like
HasDraggable and HasClass; locate the PHPDoc above the trait declaration
(HasTitle) and change the line that reads "Handles the HTML `title` global
attributes." to "Handles the HTML `title` global attribute."

🧹 Nitpick comments (2)

src/Values/Draggable.php (1)

14-15: Clarify string tokens vs booleans in doc wording.

“map to false and true” can read as booleans; consider using 'false'/'true' to match the string enum values.

💡 Suggested doc tweak

- * - Enum values map to `false` and `true`.
+ * - Enum values map to `'false'` and `'true'` tokens.

src/Element/HasWidth.php (1)

12-18: Consider refining "manipulation" terminology for immutability.

Line 14 uses "manipulation of the width attribute," which could be misleading given that line 12 explicitly states this is an "immutable API." Immutable APIs don't manipulate attributes directly; they return new instances with updated values.

Additionally, line 18's "Handles the HTML width attribute" is somewhat generic and redundant with line 12.

♻️ Suggested refinement for clearer terminology

-Provides an immutable API for setting the `width` attribute on HTML elements.
+Provides an immutable API for configuring the `width` attribute on HTML elements.
 *
-Intended for use in tags and components that require manipulation of the `width` attribute.
+Intended for use in tags and components that require the `width` attribute.
 *
 * Key features.
 * - Designed for use in tags and components.
-- Handles the HTML `width` attribute.
+- Immutably configures the HTML `width` attribute.
 * - Immutable method for setting or overriding the `width` attribute.