refactor!: significant refactor of message and modal components

[DCodeProg]

Description

This PR introduces a major architectural refactoring of the component system, transitioning from prefixed component classes (e.g., MessageButton, ModalTextInput) to unified component classes that implement specific interfaces (MessageComponent, ModalComponent). This aligns with Discord's component specification v2 and significantly improves the developer experience.

🎯 Key Changes

1. Component Interface Architecture

Introduced a new interface-based system:

• Component - Base interface for all components
• MessageComponent - Interface for components usable in messages
• ModalComponent - Interface for components usable in modals

Before:

MessageButton.primary('id', label: 'Click')
ModalTextInput('id', ...)

After:

Button.primary('id', label: 'Click') // implements MessageComponent
TextInput.short('id', ...) // implements ModalComponent

2. Component Renaming

All components renamed to remove context prefixes:

• MessageButton → Button
• MessageRowBuilder → ActionRow
• MessageFile → AttachedFile
• MessageThumbnail → Thumbnail
• MessageGallery → MediaGallery
• MessageMedia → MediaItem
• MessageContainer → Container
• MessageSection → Section
• MessageSeparator → Separator
• ModalLabel → Label
• ModalTextInput → TextInput

3. Builder API Improvements

MessageBuilder:

• Standardized method naming with add* prefix pattern
• Improved method signatures for better usability:

  // Simplified gallery creation
  builder.addGallery([item1, item2]) // was: addGallery(MediaGallery([...]))
  
  // Improved section API
  builder.addSection(
    builder: sectionBuilder,
    button: optionalButton,
    thumbnail: optionalThumbnail,
  ) // was: addSection(Section(...))

• Added factory constructors: MessageBuilder.text()
• Moved to builder/ directory

ModalBuilder:

• Replaced generic addLabel() with specific type-safe methods:

  modal.addTextInput(
    customId: 'id',
    label: 'Username',
    style: TextInputStyle.short,
  ) // was: addLabel(label: 'Username', component: TextInput.short('id'))

• Added addTextInput(), addSelectMenu(), addText() methods
• Moved to builder/ directory

4. Enhanced MediaItem & AttachedFile API

// New factory constructors
final mediaFromFile = MediaItem.fromFile(File('image.png'), 'image.png');
final mediaFromNetwork = MediaItem.fromNetwork('https://example.com/img.jpg');

// Direct MediaItem integration with auto-fetch
final file = await AttachedFile.fromMediaItem(mediaItem);

// Simplified network file creation (name now required)
final file = await AttachedFile.fromNetwork('https://example.com/file.pdf', 'file.pdf');

5. Validation & Constraints

• Button limits: addButtons() enforces max 5 buttons per row
• Gallery items: MediaGallery enforces 1-10 items constraint
• Section accessories: Validates button/thumbnail combinations

6. Comprehensive Documentation

Added extensive documentation to MessageBuilder and ModalBuilder:

• Detailed class-level overviews
• Usage instructions and best practices
• Multiple real-world examples (registration forms, feedback forms, file uploads, galleries)
• Complete parameter documentation
• Method chaining examples
• "See also" references

7. Additional Features

• Reorganized exports in api.dart and events.dart
• Method reordering for better readability

🔄 Migration Path

1. Update imports (all components exported from package:mineral/api.dart)
2. Replace prefixed component names (MessageButton → Button)
3. Update builder method names (text() → addText())
4. Use new specific methods in ModalBuilder (addTextInput() vs addLabel())
5. Leverage comprehensive documentation for examples

Related Issue

Closes #307

Type of Change

• feat
• fix
• docs
• refactor
• chore
• test

How Has This Been Tested?

Testing approach for this refactoring:

1. Compilation Testing:

   • All files compile without errors
   • No linting issues detected
   • Type safety verified through Dart analyzer

2. API Validation:

   • Verified all component constructors work correctly
   • Tested builder method chaining functionality
   • Validated factory constructors (MediaItem.fromFile(), AttachedFile.fromMediaItem())
   • Confirmed constraint enforcement (button limits, gallery items)

3. Interface Implementation:

   • Verified MessageComponent interface on message components
   • Verified ModalComponent interface on modal components
   • Tested dual implementation on SelectMenu and TextDisplay

4. Documentation Review:

   • All code examples in documentation are syntactically correct
   • Examples cover common use cases
   • Method signatures match implementation

5. Backward Compatibility:

   • Identified all breaking changes
   • Documented migration path
   • Provided before/after examples for each change

Checklist

• I have followed the Conventional Commits naming rules
• I have added tests where applicable
• All existing tests pass

---

Note: This is a breaking change release. All component names and builder APIs have been updated. Developers will need to update their code following the migration guide provided in the description.