Example Usage comment updated for all PHP components

Author: sazedul-haque

components/Accordion.php

@@ -27,19 +27,46 @@
  *     ->add_item( 'About Course', '<p>Description...</p>' )
  *     ->render();
  *
- * // Multiple items
+ * // Multiple items, first open by default
  * Accordion::make()
  *     ->add_item( 'About Course', '<p>Description...</p>' )
  *     ->add_item( 'Requirements', '<p>Prerequisites...</p>' )
  *     ->add_item( 'Instructor', '<p>Meet your instructor...</p>' )
  *     ->default_open( array( 0 ) )
  *     ->render();
  *
- * // With custom icon and template
+ * // Multiple items open by default (indices 0 and 2)
  * Accordion::make()
- *     ->add_item( 'Details', '', 'path/to/template.php', 'custom-icon' )
+ *     ->add_item( 'Overview', '<p>Course overview...</p>' )
+ *     ->add_item( 'Curriculum', '<p>Topics covered...</p>' )
+ *     ->add_item( 'FAQ', '<p>Common questions...</p>' )
+ *     ->default_open( array( 0, 2 ) )
+ *     ->render();
+ *
+ * // Only one item open at a time (allow_multiple = false)
+ * Accordion::make()
+ *     ->add_item( 'Section 1', '<p>Content 1...</p>' )
+ *     ->add_item( 'Section 2', '<p>Content 2...</p>' )
  *     ->allow_multiple( false )
  *     ->render();
+ *
+ * // With custom icon per item
+ * Accordion::make()
+ *     ->add_item( 'Resources', '', '', Icon::RESOURCES )
+ *     ->add_item( 'Downloads', '', '', Icon::DOWNLOAD_2 )
+ *     ->render();
+ *
+ * // With a PHP template file as content
+ * Accordion::make()
+ *     ->add_item( 'Details', '', get_template_directory() . '/partials/details.php' )
+ *     ->render();
+ *
+ * // Extra HTML attributes on the wrapper
+ * Accordion::make()
+ *     ->add_item( 'Notes', '<p>Some notes...</p>' )
+ *     ->attr( 'id', 'course-accordion' )
+ *     ->attr( 'class', 'my-custom-class' )
+ *     ->render();
  * ```
  *
  * @since 4.0.0
@@ -189,7 +216,7 @@ public function get(): string {
 			'multiple'    => $this->multiple,
 			'defaultOpen' => $this->default_open,
 		);
-		$alpine_json = wp_json_encode( $alpine_config );
+		$alpine_json   = wp_json_encode( $alpine_config );
 
 		// Merge custom classes.
 		$wrapper_classes = 'tutor-accordion';
@@ -206,9 +233,9 @@ public function get(): string {
 		// Build items HTML.
 		$items_html = '';
 		foreach ( $this->items as $index => $item ) {
-			$title     = isset( $item['title'] ) ? $item['title'] : '';
-			$icon      = isset( $item['icon'] ) ? $item['icon'] : '';
-			$panel_id  = 'tutor-acc-panel-' . $index;
+			$title      = isset( $item['title'] ) ? $item['title'] : '';
+			$icon       = isset( $item['icon'] ) ? $item['icon'] : '';
+			$panel_id   = 'tutor-acc-panel-' . $index;
 			$trigger_id = 'tutor-acc-trigger-' . $index;
 
 			$icon_html = $this->render_icon( $icon );
@@ -262,5 +289,4 @@ class="tutor-accordion-content"
 			$items_html
 		);
 	}
-
 }

components/Alert.php

@@ -20,11 +20,46 @@
  *
  * Example usage:
  * ```
+ * // Default (neutral) alert
  * Alert::make()
- *     ->text( 'This is an alert' )
+ *     ->text( 'Your changes have been saved.' )
+ *     ->render();
+ *
+ * // Success alert with icon
+ * Alert::make()
+ *     ->text( 'Course published successfully.' )
  *     ->variant( Alert::SUCCESS )
  *     ->icon( Icon::PRIME_CHECK_CIRCLE )
- *     ->action( '<button class="...">Resume</button>' )
+ *     ->render();
+ *
+ * // Info alert with action button
+ * Alert::make()
+ *     ->text( 'You have an incomplete quiz. Resume where you left off.' )
+ *     ->variant( Alert::INFO )
+ *     ->icon( Icon::INFO )
+ *     ->action( '<button class="tutor-btn tutor-btn-primary tutor-btn-small">Resume</button>' )
+ *     ->render();
+ *
+ * // Warning alert
+ * Alert::make()
+ *     ->text( 'Your subscription expires in 3 days.' )
+ *     ->variant( Alert::WARNING )
+ *     ->icon( Icon::WARNING )
+ *     ->render();
+ *
+ * // Error alert with custom icon size
+ * Alert::make()
+ *     ->text( 'Payment failed. Please try again.' )
+ *     ->variant( Alert::ERROR )
+ *     ->icon( Icon::CLOSE_CIRCLE, 24, 24 )
+ *     ->render();
+ *
+ * // Alert with extra HTML attributes
+ * Alert::make()
+ *     ->text( 'Draft saved.' )
+ *     ->variant( Alert::SUCCESS )
+ *     ->attr( 'id', 'draft-alert' )
+ *     ->attr( 'x-show', 'showAlert' )
  *     ->render();
  * ```
  *

components/AttachmentCard.php

@@ -18,13 +18,39 @@
  * Class AttachmentCard
  *
  * Example Usage:
+ * ```php
+ * // Basic downloadable attachment
  * AttachmentCard::make()
  *     ->file_name( 'lesson-plan.pdf' )
- *     ->file_size( '1.2 MB' )
+ *     ->file_size( '1258291' ) // bytes — size_format() is applied internally
  *     ->is_downloadable( true )
  *     ->action_attr( '@click', 'downloadFile()' )
  *     ->render();
  *
+ * // Removable attachment (delete icon)
+ * AttachmentCard::make()
+ *     ->file_name( 'assignment.docx' )
+ *     ->file_size( '524288' )
+ *     ->is_downloadable( false )
+ *     ->action_attr( '@click', 'removeFile(index)' )
+ *     ->render();
+ *
+ * // With Alpine.js dynamic bindings on title and meta
+ * AttachmentCard::make()
+ *     ->title_attr( 'x-text', 'file.name' )
+ *     ->meta_attr( 'x-text', 'formatBytes(file.size)' )
+ *     ->action_attr( '@click.stop', 'removeFile(index)' )
+ *     ->render();
+ *
+ * // With extra attributes on the wrapper
+ * AttachmentCard::make()
+ *     ->file_name( 'course-notes.pdf' )
+ *     ->file_size( '2097152' )
+ *     ->is_downloadable( true )
+ *     ->attr( 'data-id', '42' )
+ *     ->render();
+ * ```
+ *
  * @since 4.0.0
  */
 class AttachmentCard extends BaseComponent {

components/Avatar.php

@@ -24,25 +24,49 @@
  * Example usage:
  *
  * ```php
- * Avatar with user object/ID
+ * // Avatar from a WP user ID (auto-resolves photo or initials)
  * Avatar::make()
- *     ->user($user_id)
- *     ->size(Size::SIZE_56)
+ *     ->user( $user_id )
+ *     ->size( Size::SIZE_56 )
  *     ->render();
  *
- * Avatar with image source
+ * // Avatar from a WP_User object
  * Avatar::make()
- *     ->src('https://example.com/avatar.jpg')
- *     ->size(Size::SIZE_20)
+ *     ->user( $user )
+ *     ->size( Size::SIZE_40 )
  *     ->bordered()
  *     ->render();
  *
- * Avatar with initials
+ * // Avatar with explicit image URL
  * Avatar::make()
- *     ->initials('SK')
- *     ->size(Size::SIZE_32)
- *     ->rounded(false)
+ *     ->src( 'https://example.com/avatar.jpg' )
+ *     ->alt( 'John Doe' )
+ *     ->size( Size::SIZE_32 )
  *     ->render();
+ *
+ * // Avatar with initials fallback only
+ * Avatar::make()
+ *     ->initials( 'JD' )
+ *     ->size( Size::SIZE_48 )
+ *     ->render();
+ *
+ * // Avatar with square shape (no border-radius)
+ * Avatar::make()
+ *     ->user( $user_id )
+ *     ->size( Size::SIZE_64 )
+ *     ->shape( 'square' )
+ *     ->render();
+ *
+ * // Avatar with border and custom attributes
+ * Avatar::make()
+ *     ->src( 'https://example.com/pic.jpg' )
+ *     ->size( Size::SIZE_20 )
+ *     ->bordered()
+ *     ->attr( 'data-user-id', $user_id )
+ *     ->render();
+ *
+ * // Retrieve HTML string without echoing
+ * $html = Avatar::make()->user( $user_id )->size( Size::SIZE_24 )->get();
  * ```
  *
  * @since 4.0.0

components/Badge.php

@@ -20,16 +20,54 @@
  *
  * Example usage:
  * ```
+ * // Primary badge
  * Badge::make()
- *     ->label( 'Primary' )
+ *     ->label( 'New' )
  *     ->variant( Badge::PRIMARY )
+ *     ->render();
+ *
+ * // Badge with SVG icon markup
+ * Badge::make()
+ *     ->label( 'Certified' )
+ *     ->variant( Badge::SUCCESS )
  *     ->icon( '<svg>...</svg>' )
  *     ->render();
  *
+ * // Badge with icon name (SvgIcon slug)
+ * Badge::make()
+ *     ->label( 'Warning' )
+ *     ->variant( Badge::WARNING )
+ *     ->icon( Icon::WARNING, 14, 14 )
+ *     ->render();
+ *
+ * // Badge with icon as URL (img tag is generated)
+ * Badge::make()
+ *     ->label( 'Verified' )
+ *     ->variant( Badge::SUCCESS_SOLID )
+ *     ->icon( 'https://example.com/check.png', 16, 16 )
+ *     ->render();
+ *
+ * // Rounded (pill) badge
  * Badge::make()
  *     ->label( 'Points: 20' )
+ *     ->variant( Badge::HIGHLIGHT )
  *     ->rounded()
  *     ->render();
+ *
+ * // Error / disabled badge without icon
+ * Badge::make()
+ *     ->label( 'Inactive' )
+ *     ->variant( Badge::DISABLED )
+ *     ->render();
+ *
+ * // Badge with no variant (default style) and extra attrs
+ * Badge::make()
+ *     ->label( 'Draft' )
+ *     ->attr( 'data-status', 'draft' )
+ *     ->render();
+ *
+ * // Retrieve HTML string without echoing
+ * $html = Badge::make()->label( 'Info' )->variant( Badge::INFO )->get();
  * ```
  *
  * @since 4.0.0

components/Button.php

@@ -15,7 +15,6 @@
 
 use Tutor\Components\Constants\Size;
 use Tutor\Components\Constants\Variant;
-use Tutor\Components\Constants\Color;
 
 defined( 'ABSPATH' ) || exit;
 
@@ -24,13 +23,87 @@
  *
  * Example usage:
  * ```
+ * // Primary button (default)
  * Button::make()
  *     ->label( 'Enroll Now' )
+ *     ->render();
+ *
+ * // Button with size and variant
+ * Button::make()
+ *     ->label( 'Save Changes' )
  *     ->size( Size::LARGE )
  *     ->variant( Variant::PRIMARY )
- *     ->icon( 'tutor-icon-play' )
- *     ->attr( 'data-id', 101 )
  *     ->render();
+ *
+ * // Button with left icon
+ * Button::make()
+ *     ->label( 'Add Course' )
+ *     ->icon( Icon::PLUS )
+ *     ->size( Size::MEDIUM )
+ *     ->variant( Variant::PRIMARY )
+ *     ->render();
+ *
+ * // Button with right icon and custom icon size/color
+ * Button::make()
+ *     ->label( 'Download' )
+ *     ->icon( Icon::DOWNLOAD_2, 'right', 18, Color::BRAND )
+ *     ->variant( Variant::OUTLINE )
+ *     ->render();
+ *
+ * // Icon-only button (no visible label, uses aria-label)
+ * Button::make()
+ *     ->label( 'Delete' )
+ *     ->icon( Icon::DELETE_2 )
+ *     ->icon_only()
+ *     ->variant( Variant::GHOST )
+ *     ->size( Size::SMALL )
+ *     ->render();
+ *
+ * // Disabled button
+ * Button::make()
+ *     ->label( 'Submit' )
+ *     ->variant( Variant::PRIMARY )
+ *     ->disabled()
+ *     ->render();
+ *
+ * // Block (full-width) button
+ * Button::make()
+ *     ->label( 'Continue' )
+ *     ->variant( Variant::PRIMARY )
+ *     ->block()
+ *     ->render();
+ *
+ * // Link-styled button rendered as <a> tag
+ * Button::make()
+ *     ->label( 'View Course' )
+ *     ->variant( Variant::LINK )
+ *     ->tag( 'a' )
+ *     ->attr( 'href', get_permalink( $course_id ) )
+ *     ->render();
+ *
+ * // Destructive button
+ * Button::make()
+ *     ->label( 'Delete Course' )
+ *     ->variant( Variant::DESTRUCTIVE )
+ *     ->size( Size::SMALL )
+ *     ->render();
+ *
+ * // Secondary/outline button with data attribute
+ * Button::make()
+ *     ->label( 'Cancel' )
+ *     ->variant( Variant::SECONDARY )
+ *     ->attr( 'data-id', $course_id )
+ *     ->render();
+ *
+ * // Button with RTL-flippable directional icon
+ * Button::make()
+ *     ->label( 'Next' )
+ *     ->icon( Icon::CHEVRON_RIGHT, 'right' )
+ *     ->flip_rtl()
+ *     ->render();
+ *
+ * // Retrieve HTML string without echoing
+ * $html = Button::make()->label( 'Get Started' )->variant( Variant::PRIMARY )->get();
  * ```
  *
  * @since 4.0.0
@@ -403,5 +476,4 @@ public function get(): string {
 
 		return $this->component_string;
 	}
-
 }