├── composer-require-checker.json
├── .phpunit-watcher.yml
├── infection.json.dist
├── src
    ├── ButtonSize.php
    ├── ProgressVariant.php
    ├── Utility
    │   ├── TogglerType.php
    │   ├── Responsive.php
    │   ├── Sizing.php
    │   ├── TextBackgroundColor.php
    │   ├── TextColor.php
    │   ├── BackgroundColor.php
    │   └── AlignItems.php
    ├── NavBarPlacement.php
    ├── ButtonType.php
    ├── OffcanvasPlacement.php
    ├── DropdownItemType.php
    ├── NavBarExpand.php
    ├── DropdownAutoClose.php
    ├── AlertVariant.php
    ├── NavStyle.php
    ├── ModalDialogFullScreenSize.php
    ├── DropdownDirection.php
    ├── NavLayout.php
    ├── Assets
    │   ├── BootstrapCdnAsset.php
    │   └── BootstrapAsset.php
    ├── DropdownAlignment.php
    ├── ButtonVariant.php
    ├── BreadcrumbLink.php
    ├── AccordionItem.php
    ├── ProgressStack.php
    ├── ButtonToolbar.php
    ├── Toggler.php
    ├── ButtonGroup.php
    ├── CarouselItem.php
    ├── NavLink.php
    ├── DropdownItem.php
    ├── Collapse.php
    ├── Progress.php
    ├── Breadcrumbs.php
    ├── Button.php
    └── Alert.php
├── CHANGELOG.md
├── psalm.xml
├── rector.php
├── LICENSE.md
├── .styleci.yml
├── composer.json
└── README.md


/composer-require-checker.json:
--------------------------------------------------------------------------------
1 | {
2 |     "symbol-whitelist": [
3 |         "Yiisoft\\Assets\\AssetBundle",
4 |         "Yiisoft\\Files\\PathMatcher\\PathMatcher"
5 |     ]
6 | }
7 | 


--------------------------------------------------------------------------------
/.phpunit-watcher.yml:
--------------------------------------------------------------------------------
 1 | watch:
 2 |     directories:
 3 |         - src
 4 |         - tests
 5 |     fileMask: '*.php'
 6 | notifications:
 7 |     passingTests: false
 8 |     failingTests: false
 9 | phpunit:
10 |     binaryPath: vendor/bin/phpunit
11 |     timeout: 180
12 | 


--------------------------------------------------------------------------------
/infection.json.dist:
--------------------------------------------------------------------------------
 1 | {
 2 |     "source": {
 3 |         "directories": [
 4 |             "src"
 5 |         ]
 6 |     },
 7 |     "logs": {
 8 |         "text": "php:\/\/stderr",
 9 |         "stryker": {
10 |             "report": "master"
11 |         }
12 |     },
13 |     "mutators": {
14 |         "@default": true
15 |     }
16 | }
17 | 


--------------------------------------------------------------------------------
/src/ButtonSize.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Size for the {@see Button} component.
 9 |  */
10 | enum ButtonSize: string
11 | {
12 |     /**
13 |      * Small size.
14 |      */
15 |     case SMALL = 'btn-sm';
16 |     /**
17 |      * Large size.
18 |      */
19 |     case LARGE = 'btn-lg';
20 | }
21 | 


--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
 1 | # Yii Framework bootstrap5 extension Change Log
 2 | 
 3 | ## 1.0.1 under development
 4 | 
 5 | - Enh #287: Allow `Dropdown::togglerVariant()` to be `null`, avoiding it setting a variant class (@Mister-42)
 6 | - Bug #288: Add support for custom togglerClasses in `Dropdown` widget, and `addDropdownClass()` method (@terabytesoftw)
 7 | - Enh #291: Add `navId()` method to `NavBar` widget (@terabytesoftw)
 8 | 
 9 | ## 1.0.0 April 13, 2025
10 | 
11 | - Initial release
12 | 


--------------------------------------------------------------------------------
/src/ProgressVariant.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Variant for the progress component.
 9 |  *
10 |  * https://getbootstrap.com/docs/5.3/components/progress/
11 |  */
12 | enum ProgressVariant: string
13 | {
14 |     /**
15 |      * The progress bar will be animated and striped.
16 |      */
17 |     case ANIMATED_STRIPED = 'progress-bar-striped progress-bar-animated';
18 |     /**
19 |      * The progress bar will be striped.
20 |      */
21 |     case STRIPED = 'progress-bar-striped';
22 | }
23 | 


--------------------------------------------------------------------------------
/src/Utility/TogglerType.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Utility;
 6 | 
 7 | /**
 8 |  * Toggler types.
 9 |  */
10 | enum TogglerType: string
11 | {
12 |     /**
13 |      * Button toggle type.
14 |      */
15 |     case BUTTON = 'button';
16 |     /**
17 |      * Collapse toggle type.
18 |      */
19 |     case COLLAPSE = 'collapse';
20 |     /**
21 |      * Dropdown toggle type.
22 |      */
23 |     case DROPDOWN = 'dropdown';
24 |     /**
25 |      * Modal toggle type.
26 |      */
27 |     case MODAL = 'modal';
28 |     /**
29 |      * Popover toggle type.
30 |      */
31 |     case POPOVER = 'popover';
32 |     /**
33 |      * Tooltip toggle type.
34 |      */
35 |     case TOOLTIP = 'tooltip';
36 | }
37 | 


--------------------------------------------------------------------------------
/src/NavBarPlacement.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * The placement of a Bootstrap5 navbar.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/navbar/#placement
11 |  */
12 | enum NavBarPlacement: string
13 | {
14 |     /**
15 |      * Fixed to the bottom of the viewport.
16 |      */
17 |     case FIXED_BOTTOM = 'fixed-bottom';
18 |     /**
19 |      * Fixed to the top of the viewport.
20 |      */
21 |     case FIXED_TOP = 'fixed-top';
22 |     /**
23 |      * Sticks to the bottom of the viewport when scrolling.
24 |      */
25 |     case STICKY_BOTTOM = 'sticky-bottom';
26 |     /**
27 |      * Sticks to the top of the viewport when scrolling.
28 |      */
29 |     case STICKY_TOP = 'sticky-top';
30 | }
31 | 


--------------------------------------------------------------------------------
/src/ButtonType.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Types for the {@see Button} component.
 9 |  */
10 | enum ButtonType: string
11 | {
12 |     /**
13 |      * Link button, renders as `<a>` element.
14 |      */
15 |     case LINK = 'link';
16 |     /**
17 |      * Reset button, renders as `<button type="reset">`.
18 |      */
19 |     case RESET = 'reset';
20 |     /**
21 |      * Reset input, renders as `<input type="reset">`.
22 |      */
23 |     case RESET_INPUT = 'reset-input';
24 |     /**
25 |      * Submit button, renders as `<button type="submit">`.
26 |      */
27 |     case SUBMIT = 'submit';
28 |     /**
29 |      * Submit input, renders as `<input type="submit">`.
30 |      */
31 |     case SUBMIT_INPUT = 'submit-input';
32 | }
33 | 


--------------------------------------------------------------------------------
/src/OffcanvasPlacement.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * The placement of a Bootstrap5 offcanvas.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/offcanvas/#placement
11 |  */
12 | enum OffcanvasPlacement: string
13 | {
14 |     /**
15 |      * Places offcanvas on the bottom of the viewport.
16 |      */
17 |     case BOTTOM = 'offcanvas-bottom';
18 |     /**
19 |      * Places offcanvas on the right of the viewport
20 |      */
21 |     case END = 'offcanvas-end';
22 |     /**
23 |      * Places offcanvas on the left of the viewport (shown above).
24 |      */
25 |     case START = 'offcanvas-start';
26 |     /**
27 |      * Places offcanvas on the top of the viewport.
28 |      */
29 |     case TOP = 'offcanvas-top';
30 | }
31 | 


--------------------------------------------------------------------------------
/src/Utility/Responsive.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Utility;
 6 | 
 7 | /**
 8 |  * Responsive utilities.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/extend/approach/#responsive
11 |  */
12 | enum Responsive: string
13 | {
14 |     /**
15 |      * Extra small devices (portrait phones, less than 576px).
16 |      */
17 |     case SM = 'sm';
18 |     /**
19 |      * Small devices (landscape phones, 576px and up).
20 |      */
21 |     case MD = 'md';
22 |     /**
23 |      * Medium devices (tablets, 768px and up).
24 |      */
25 |     case LG = 'lg';
26 |     /**
27 |      * Large devices (desktops, 992px and up).
28 |      */
29 |     case XL = 'xl';
30 |     /**
31 |      * Extra large devices (large desktops, 1200px and up).
32 |      */
33 |     case XXL = 'xxl';
34 | }
35 | 


--------------------------------------------------------------------------------
/src/DropdownItemType.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Defines the types of items that can be used in a Bootstrap dropdown.
 9 |  *
10 |  * @see DropdownItem
11 |  */
12 | enum DropdownItemType: string
13 | {
14 |     /**
15 |      * A clickable button item.
16 |      */
17 |     case BUTTON = 'button';
18 |     /**
19 |      * Custom HTML content item.
20 |      */
21 |     case CUSTOM_CONTENT = 'custom-content';
22 |     /**
23 |      * A horizontal divider line.
24 |      */
25 |     case DIVIDER = 'divider';
26 |     /**
27 |      * A header item for grouping other items.
28 |      */
29 |     case HEADER = 'header';
30 |     /**
31 |      * A standard link item.
32 |      */
33 |     case LINK = 'link';
34 |     /**
35 |      * A text-only item.
36 |      */
37 |     case TEXT = 'text';
38 | }
39 | 


--------------------------------------------------------------------------------
/src/NavBarExpand.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Expand sizes for a Bootstrap5 {@see NavBar}.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/navbar/#how-it-works
11 |  */
12 | enum NavBarExpand: string
13 | {
14 |     /**
15 |      * Expand on small devices (≥576px).
16 |      */
17 |     case SM = 'navbar-expand-sm';
18 |     /**
19 |      * Expand on medium devices (≥768px).
20 |      */
21 |     case MD = 'navbar-expand-md';
22 |     /**
23 |      * Expand on large devices (≥992px).
24 |      */
25 |     case LG = 'navbar-expand-lg';
26 |     /**
27 |      * Expand on extra large devices (≥1200px).
28 |      */
29 |     case XL = 'navbar-expand-xl';
30 |     /**
31 |      * Expand on extra-extra large devices (≥1400px).
32 |      */
33 |     case XXL = 'navbar-expand-xxl';
34 | }
35 | 


--------------------------------------------------------------------------------
/src/DropdownAutoClose.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Auto close behavior for dropdowns.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/dropdowns/#auto-close-behavior
11 |  */
12 | enum DropdownAutoClose: string
13 | {
14 |     /**
15 |      * The dropdown will be closed by clicking outside or inside the dropdown menu.
16 |      */
17 |     case TRUE = 'true';
18 |     /**
19 |      * The dropdown will be closed by clicking the toggle button and manually calling hide or toggle method.
20 |      * (Also will not be closed by pressing `Esc` key)
21 |      */
22 |     case FALSE = 'false';
23 |     /**
24 |      * The dropdown will be closed (only) by clicking inside the dropdown menu.
25 |      */
26 |     case INSIDE = 'inside';
27 |     /**
28 |      * The dropdown will be closed (only) by clicking outside the dropdown menu.
29 |      */
30 |     case OUTSIDE = 'outside';
31 | }
32 | 


--------------------------------------------------------------------------------
/src/AlertVariant.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Variants for the alert component.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/alerts/#examples
11 |  */
12 | enum AlertVariant: string
13 | {
14 |     /**
15 |      * Primary variant.
16 |      */
17 |     case PRIMARY = 'alert-primary';
18 |     /**
19 |      * Secondary variant.
20 |      */
21 |     case SECONDARY = 'alert-secondary';
22 |     /**
23 |      * Success variant.
24 |      */
25 |     case SUCCESS = 'alert-success';
26 |     /**
27 |      * Danger variant.
28 |      */
29 |     case DANGER = 'alert-danger';
30 |     /**
31 |      * Warning variant.
32 |      */
33 |     case WARNING = 'alert-warning';
34 |     /**
35 |      * Info variant.
36 |      */
37 |     case INFO = 'alert-info';
38 |     /**
39 |      * Light variant.
40 |      */
41 |     case LIGHT = 'alert-light';
42 |     /**
43 |      * Dark variant.
44 |      */
45 |     case DARK = 'alert-dark';
46 | }
47 | 


--------------------------------------------------------------------------------
/src/NavStyle.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  *  Styles for the nav component.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/navs-tabs/#horizontal-alignment
11 |  */
12 | enum NavStyle: string
13 | {
14 |     /**
15 |      * Horizontal navigation component for the top of an application. It is the most common navigation pattern for
16 |      * desktop apps. Use it with `.navbar-nav` to apply the default styling.
17 |      */
18 |     case NAVBAR = 'navbar-nav me-auto mb-2 mb-lg-0';
19 |     /**
20 |      * Take that same HTML, but use `.nav-pills` instead.
21 |      */
22 |     case PILLS = 'nav-pills';
23 |     /**
24 |      * Takes the basic nav from above and adds the `.nav-tabs` class to generate a tabbed interface. Use them to create
25 |      * tabbable regions with our tab JavaScript plugin.
26 |      */
27 |     case TABS = 'nav-tabs';
28 |     /**
29 |      * Take that same HTML, but use `.nav-underline` instead.
30 |      */
31 |     case UNDERLINE = 'nav-underline';
32 | }
33 | 


--------------------------------------------------------------------------------
/src/ModalDialogFullScreenSize.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Modal dialog fullscreen.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/modal/#fullscreen-modal
11 |  */
12 | enum ModalDialogFullScreenSize: string
13 | {
14 |     /**
15 |      * The full-screen variant.
16 |      */
17 |     case FULLSCREEN = 'modal-fullscreen';
18 |     /**
19 |      * The full-screen sm down variant.
20 |      */
21 |     case FULLSCREEN_SM_DOWN = 'modal-fullscreen-sm-down';
22 |     /**
23 |      * The full-screen md down variant.
24 |      */
25 |     case FULLSCREEN_MD_DOWN = 'modal-fullscreen-md-down';
26 |     /**
27 |      * The full-screen lg down variant.
28 |      */
29 |     case FULLSCREEN_LG_DOWN = 'modal-fullscreen-lg-down';
30 |     /**
31 |      * The full-screen xl down variant.
32 |      */
33 |     case FULLSCREEN_XL_DOWN = 'modal-fullscreen-xl-down';
34 |     /**
35 |      * The full-screen xxl down variant.
36 |      */
37 |     case FULLSCREEN_XXL_DOWN = 'modal-fullscreen-xxl-down';
38 | }
39 | 


--------------------------------------------------------------------------------
/psalm.xml:
--------------------------------------------------------------------------------
 1 | <?xml version="1.0"?>
 2 | <psalm
 3 |     errorLevel="2"
 4 |     ensureOverrideAttribute="false"
 5 |     findUnusedBaselineEntry="true"
 6 |     findUnusedCode="false"
 7 |     resolveFromConfigFile="true"
 8 |     strictBinaryOperands="false"
 9 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
10 |     xmlns="https://getpsalm.org/schema/config"
11 |     xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
12 | >
13 |     <projectFiles>
14 |         <directory name="src" />
15 |         <ignoreFiles>
16 |             <directory name="src/Assets" />
17 |             <directory name="vendor" />
18 |         </ignoreFiles>
19 |     </projectFiles>
20 | 
21 |     <issueHandlers>
22 |         <MixedAssignment errorLevel="suppress" />
23 |         <PropertyNotSetInConstructor errorLevel="suppress" />
24 |         <RedundantPropertyInitializationCheck errorLevel="suppress" />
25 |         <RiskyTruthyFalsyComparison errorLevel="suppress" />
26 |         <MissingOverrideAttribute errorLevel="suppress" />
27 |     </issueHandlers>
28 | </psalm>
29 | 


--------------------------------------------------------------------------------
/src/Utility/Sizing.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Utility;
 6 | 
 7 | /**
 8 |  * Width and height utilities.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/utilities/sizing/
11 |  */
12 | enum Sizing: string
13 | {
14 |     /**
15 |      * Width auto.
16 |      */
17 |     case WIDTH_AUTO = 'w-auto';
18 |     /**
19 |      * Width 25%.
20 |      */
21 |     case WIDTH_25 = 'w-25';
22 |     /**
23 |      * Width 50%.
24 |      */
25 |     case WIDTH_50 = 'w-50';
26 |     /**
27 |      * Width 75%.
28 |      */
29 |     case WIDTH_75 = 'w-75';
30 |     /**
31 |      * Width 100%.
32 |      */
33 |     case WIDTH_100 = 'w-100';
34 |     /**
35 |      * Height auto.
36 |      */
37 |     case HEIGHT_AUTO = 'h-auto';
38 |     /**
39 |      * Height 25%.
40 |      */
41 |     case HEIGHT_25 = 'h-25';
42 |     /**
43 |      * Height 50%.
44 |      */
45 |     case HEIGHT_50 = 'h-50';
46 |     /**
47 |      * Height 75%.
48 |      */
49 |     case HEIGHT_75 = 'h-75';
50 |     /**
51 |      * Height 100%.
52 |      */
53 |     case HEIGHT_100 = 'h-100';
54 | }
55 | 


--------------------------------------------------------------------------------
/src/DropdownDirection.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Direction for the dropdown component.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/dropdowns/#directions
11 |  */
12 | enum DropdownDirection: string
13 | {
14 |     /**
15 |      * Make the dropdown menu centered below the toggle with `.dropdown-center` on the parent element.
16 |      */
17 |     case CENTERED = 'dropdown-center';
18 |     /**
19 |      * Trigger dropdown menus above elements by adding `.dropup` to the parent element.
20 |      */
21 |     case DROPUP = 'btn-group dropup';
22 |     /**
23 |      * Make the dropup menu centered above the toggle with `.dropup-center` on the parent element.
24 |      */
25 |     case DROPUP_CENTERED = 'dropup-center dropup';
26 |     /**
27 |      * Trigger dropdown menus at the right of the elements by adding `.dropend` to the parent element.
28 |      */
29 |     case DROPEND = 'btn-group dropend';
30 |     /**
31 |      * Trigger dropdown menus at the left of the elements by adding `.dropstart` to the parent element.
32 |      */
33 |     case DROPSTART = 'btn-group dropstart';
34 | }
35 | 


--------------------------------------------------------------------------------
/src/Utility/TextBackgroundColor.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Utility;
 6 | 
 7 | /**
 8 |  * Text background color enum.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/helpers/color-background/
11 |  */
12 | enum TextBackgroundColor: string
13 | {
14 |     /**
15 |      * "Primary text" color background.
16 |      */
17 |     case PRIMARY = 'text-bg-primary';
18 |     /**
19 |      * "Secondary text" color background.
20 |      */
21 |     case SECONDARY = 'text-bg-secondary';
22 |     /**
23 |      * "Success text" color background.
24 |      */
25 |     case SUCCESS = 'text-bg-success';
26 |     /**
27 |      * "Danger text" color background.
28 |      */
29 |     case DANGER = 'text-bg-danger';
30 |     /**
31 |      * "Warning text" color background.
32 |      */
33 |     case WARNING = 'text-bg-warning';
34 |     /**
35 |      * "Info text" color background.
36 |      */
37 |     case INFO = 'text-bg-info';
38 |     /**
39 |      * "Light text" color background.
40 |      */
41 |     case LIGHT = 'text-bg-light';
42 |     /**
43 |      * "Dark text" color background.
44 |      */
45 |     case DARK = 'text-bg-dark';
46 | }
47 | 


--------------------------------------------------------------------------------
/src/NavLayout.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Layouts for the nav component.
 9 |  *
10 |  * @link https://getbootstrap.com/docs/5.3/components/navs-tabs/#fill-and-justify
11 |  * @link https://getbootstrap.com/docs/5.3/components/navs-tabs/#horizontal-alignment
12 |  * @link https://getbootstrap.com/docs/5.3/components/navs-tabs/#vertical
13 |  */
14 | enum NavLayout: string
15 | {
16 |     /**
17 |      * Change the horizontal alignment of your nav with flexbox utilities. By default, navs are left-aligned, but you
18 |      * can change them to center or right-aligned.
19 |      */
20 |     case CENTER = 'justify-content-center';
21 |     /**
22 |      * Take that same HTML, but use `.nav-borders` instead.
23 |      */
24 |     case FILL = 'nav-fill';
25 |     /**
26 |      * All horizontal space will be occupied by nav links, but unlike the `.nav-fill` above, every nav item will be the
27 |      * same width.
28 |      */
29 |     case JUSTIFY = 'nav-justified';
30 |     /**
31 |      * Right alignment of nav items
32 |      */
33 |     case RIGHT = 'justify-content-end';
34 |     /**
35 |      * Stack navigation items vertically
36 |      */
37 |     case VERTICAL = 'flex-column';
38 | }
39 | 


--------------------------------------------------------------------------------
/src/Assets/BootstrapCdnAsset.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Assets;
 6 | 
 7 | use Yiisoft\Assets\AssetManager;
 8 | use Yiisoft\Assets\AssetBundle;
 9 | 
10 | /**
11 |  * Asset bundle for the Bootstrap files served via CDN.
12 |  *
13 |  * @psalm-import-type CssFile from AssetManager
14 |  * @psalm-import-type JsFile from AssetManager
15 |  */
16 | final class BootstrapCdnAsset extends AssetBundle
17 | {
18 |     public bool $cdn = true;
19 | 
20 |     /**
21 |      * @psalm-var array<array-key, string|CssFile>
22 |      */
23 |     public array $css = [
24 |         [
25 |             'https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/css/bootstrap.min.css',
26 |             'integrity' => 'sha384-giJF6kkoqNQ00vy+HMDP7azOuL0xtbfIcaT9wjKHr8RbDVddVHyTfAAsrekwKmP1',
27 |             'crossorigin' => 'anonymous',
28 |         ],
29 |     ];
30 | 
31 |     /**
32 |      * @psalm-var array<array-key, string|JsFile>
33 |      */
34 |     public array $js = [
35 |         [
36 |             'https://cdn.jsdelivr.net/npm/bootstrap@5.0.0-beta1/dist/js/bootstrap.bundle.min.js',
37 |             'integrity' => 'sha384-ygbV9kiqUc6oa4msXn9868pTtWMgiQaeYH7/t7LECLbyPA2x65Kgf80OJFdroafW',
38 |             'crossorigin' => 'anonymous',
39 |         ],
40 |     ];
41 | }
42 | 


--------------------------------------------------------------------------------
/src/Assets/BootstrapAsset.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5\Assets;
 6 | 
 7 | use Yiisoft\Assets\AssetManager;
 8 | use Yiisoft\Assets\AssetBundle;
 9 | use Yiisoft\Files\PathMatcher\PathMatcher;
10 | 
11 | /**
12 |  * Asset bundle for the Bootstrap files.
13 |  *
14 |  * @psalm-import-type CssFile from AssetManager
15 |  * @psalm-import-type JsFile from AssetManager
16 |  */
17 | final class BootstrapAsset extends AssetBundle
18 | {
19 |     public ?string $basePath = '@assets';
20 | 
21 |     public ?string $baseUrl = '@assetsUrl';
22 | 
23 |     public ?string $sourcePath = '@npm/bootstrap/dist';
24 | 
25 |     /**
26 |      * @psalm-var array<array-key, string|CssFile>
27 |      */
28 |     public array $css = [
29 |         'css/bootstrap.css',
30 |     ];
31 | 
32 |     /**
33 |      * @psalm-var array<array-key, string|JsFile>
34 |      */
35 |     public array $js = [
36 |         'js/bootstrap.bundle.js',
37 |     ];
38 | 
39 |     public function __construct()
40 |     {
41 |         $pathMatcher = new PathMatcher();
42 | 
43 |         $this->publishOptions = [
44 |             'filter' => $pathMatcher->only(
45 |                 '**css/bootstrap.css',
46 |                 '**css/bootstrap.css.map',
47 |                 '**js/bootstrap.bundle.js',
48 |                 '**js/bootstrap.bundle.js.map',
49 |             ),
50 |         ];
51 |     }
52 | }
53 | 


--------------------------------------------------------------------------------
/rector.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | return static function (Rector\Config\RectorConfig $rectorConfig): void {
 6 |     $rectorConfig->parallel();
 7 | 
 8 |     $rectorConfig->importNames();
 9 | 
10 |     $rectorConfig->phpVersion(\Rector\ValueObject\PhpVersion::PHP_81);
11 | 
12 |     $rectorConfig->paths(
13 |         [
14 |             __DIR__ . '/src',
15 |             __DIR__ . '/tests',
16 |         ],
17 |     );
18 | 
19 |     $rectorConfig->sets(
20 |         [
21 |             \Rector\Set\ValueObject\SetList::PHP_84,
22 |             \Rector\Set\ValueObject\LevelSetList::UP_TO_PHP_84,
23 |             \Rector\Set\ValueObject\SetList::CODE_QUALITY,
24 |             \Rector\Set\ValueObject\SetList::CODING_STYLE,
25 |             \Rector\Set\ValueObject\SetList::TYPE_DECLARATION,
26 |         ],
27 |     );
28 | 
29 |     $rectorConfig::configure()->withConfiguredRule(
30 |         \Rector\CodeQuality\Rector\BooleanAnd\SimplifyEmptyArrayCheckRector::class,
31 |         [
32 |             'include_numeric_string_check' => false,
33 |         ],
34 |     );
35 | 
36 |     $rectorConfig->skip(
37 |         [
38 |             \Rector\CodingStyle\Rector\Property\SplitGroupedPropertiesRector::class,
39 |             \Rector\CodingStyle\Rector\Stmt\NewlineAfterStatementRector::class,
40 |             \Rector\Php73\Rector\String_\SensitiveHereNowDocRector::class,
41 |             \Rector\Php74\Rector\Closure\ClosureToArrowFunctionRector::class,
42 |             \Rector\Php81\Rector\Property\ReadOnlyPropertyRector::class,
43 |         ],
44 |     );
45 | };
46 | 


--------------------------------------------------------------------------------
/LICENSE.md:
--------------------------------------------------------------------------------
 1 | Copyright © 2008 by Yii Software (https://www.yiiframework.com/)
 2 | All rights reserved.
 3 | 
 4 | Redistribution and use in source and binary forms, with or without
 5 | modification, are permitted provided that the following conditions
 6 | are met:
 7 | 
 8 |  * Redistributions of source code must retain the above copyright
 9 |    notice, this list of conditions and the following disclaimer.
10 |  * Redistributions in binary form must reproduce the above copyright
11 |    notice, this list of conditions and the following disclaimer in
12 |    the documentation and/or other materials provided with the
13 |    distribution.
14 |  * Neither the name of Yii Software nor the names of its
15 |    contributors may be used to endorse or promote products derived
16 |    from this software without specific prior written permission.
17 | 
18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
21 | FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
22 | COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
23 | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
24 | BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25 | LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 | LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
28 | ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 | POSSIBILITY OF SUCH DAMAGE.
30 | 


--------------------------------------------------------------------------------
/src/DropdownAlignment.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Alignment for the dropdown component.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/dropdowns/#alignment-options
11 |  */
12 | enum DropdownAlignment: string
13 | {
14 |     /**
15 |      * Aligns the dropdown menu to the end of the dropdown toggle.
16 |      */
17 |     case END = 'dropdown-menu-end';
18 |     /**
19 |      * Aligns the dropdown menu to the end of the dropdown toggle on the small breakpoint.
20 |      */
21 |     case SM_END = 'dropdown-menu-sm-end';
22 |     /**
23 |      * Aligns the dropdown menu to the end of the dropdown toggle on the medium breakpoint.
24 |      */
25 |     case MD_END = 'dropdown-menu-md-end';
26 |     /**
27 |      * Aligns the dropdown menu to the end of the dropdown toggle on the large breakpoint.
28 |      */
29 |     case LG_END = 'dropdown-menu-lg-end';
30 |     /**
31 |      * Aligns the dropdown menu to the end of the dropdown toggle on the extra-large breakpoint.
32 |      */
33 |     case XL_END = 'dropdown-menu-xl-end';
34 |     /**
35 |      * Aligns the dropdown menu to the end of the dropdown toggle on the extra-extra-large breakpoint.
36 |      */
37 |     case XXL_END = 'dropdown-menu-xxl-end';
38 |     /**
39 |      * Aligns the dropdown menu to the start of the dropdown toggle.
40 |      */
41 |     case SM_START = 'dropdown-menu-sm-start';
42 |     /**
43 |      * Aligns the dropdown menu to the start of the dropdown toggle on the medium breakpoint.
44 |      */
45 |     case MD_START = 'dropdown-menu-md-start';
46 |     /**
47 |      * Aligns the dropdown menu to the start of the dropdown toggle on the large breakpoint.
48 |      */
49 |     case LG_START = 'dropdown-menu-lg-start';
50 |     /**
51 |      * Aligns the dropdown menu to the start of the dropdown toggle on the extra-large breakpoint.
52 |      */
53 |     case XL_START = 'dropdown-menu-xl-start';
54 |     /**
55 |      * Aligns the dropdown menu to the start of the dropdown toggle on the extra-extra-large breakpoint.
56 |      */
57 |     case XXL_START = 'dropdown-menu-xxl-start';
58 | }
59 | 


--------------------------------------------------------------------------------
/src/ButtonVariant.php:
--------------------------------------------------------------------------------
 1 | <?php
 2 | 
 3 | declare(strict_types=1);
 4 | 
 5 | namespace Yiisoft\Bootstrap5;
 6 | 
 7 | /**
 8 |  * Variants for the {@see Button} component.
 9 |  *
10 |  * @see https://getbootstrap.com/docs/5.3/components/buttons/#variants
11 |  * @see https://getbootstrap.com/docs/5.3/components/buttons/#outline-buttons
12 |  */
13 | enum ButtonVariant: string
14 | {
15 |     /**
16 |      * Primary button variant.
17 |      */
18 |     case PRIMARY = 'btn-primary';
19 |     /**
20 |      * Secondary button variant.
21 |      */
22 |     case SECONDARY = 'btn-secondary';
23 |     /**
24 |      * Success button variant.
25 |      */
26 |     case SUCCESS = 'btn-success';
27 |     /**
28 |      * Danger button variant.
29 |      */
30 |     case DANGER = 'btn-danger';
31 |     /**
32 |      * Warning button variant.
33 |      */
34 |     case WARNING = 'btn-warning';
35 |     /**
36 |      * Info button variant.
37 |      */
38 |     case INFO = 'btn-info';
39 |     /**
40 |      * Light button variant.
41 |      */
42 |     case LIGHT = 'btn-light';
43 |     /**
44 |      * Link button variant.
45 |      */
46 |     case LINK = 'btn-link';
47 |     /**
48 |      * Dark button variant.
49 |      */
50 |     case DARK = 'btn-dark';
51 |     /**
52 |      * Outline primary button variant.
53 |      */
54 |     case OUTLINE_PRIMARY = 'btn-outline-primary';
55 |     /**
56 |      * Outline secondary button variant.
57 |      */
58 |     case OUTLINE_SECONDARY = 'btn-outline-secondary';
59 |     /**
60 |      * Outline success button variant.
61 |      */
62 |     case OUTLINE_SUCCESS = 'btn-outline-success';
63 |     /**
64 |      * Outline danger button variant.
65 |      */
66 |     case OUTLINE_DANGER = 'btn-outline-danger';
67 |     /**
68 |      * Outline warning button variant.
69 |      */
70 |     case OUTLINE_WARNING = 'btn-outline-warning';
71 |     /**
72 |      * Outline info button variant.
73 |      */
74 |     case OUTLINE_INFO = 'btn-outline-info';
75 |     /**
76 |      * Outline light button variant.
77 |      */
78 |     case OUTLINE_LIGHT = 'btn-outline-light';
79 |     /**
80 |      * Outline dark button variant.
81 |      */
82 |     case OUTLINE_DARK = 'btn-outline-dark';
83 | }
84 | 


--------------------------------------------------------------------------------
/.styleci.yml:
--------------------------------------------------------------------------------
 1 | preset: psr12
 2 | risky: true
 3 | 
 4 | version: 8.1
 5 | 
 6 | finder:
 7 |   exclude:
 8 |     - docs
 9 |     - vendor
10 |   not-name:
11 |     - "rector.php"
12 | 
13 | enabled:
14 |   - alpha_ordered_traits
15 |   - array_indentation
16 |   - array_push
17 |   - combine_consecutive_issets
18 |   - combine_consecutive_unsets
19 |   - combine_nested_dirname
20 |   - declare_strict_types
21 |   - dir_constant
22 |   - fully_qualified_strict_types
23 |   - function_to_constant
24 |   - hash_to_slash_comment
25 |   - is_null
26 |   - logical_operators
27 |   - magic_constant_casing
28 |   - magic_method_casing
29 |   - method_separation
30 |   - modernize_types_casting
31 |   - native_function_casing
32 |   - native_function_type_declaration_casing
33 |   - no_alias_functions
34 |   - no_empty_comment
35 |   - no_empty_phpdoc
36 |   - no_empty_statement
37 |   - no_extra_block_blank_lines
38 |   - no_short_bool_cast
39 |   - no_superfluous_elseif
40 |   - no_unneeded_control_parentheses
41 |   - no_unneeded_curly_braces
42 |   - no_unneeded_final_method
43 |   - no_unset_cast
44 |   - no_unused_imports
45 |   - no_unused_lambda_imports
46 |   - no_useless_else
47 |   - no_useless_return
48 |   - normalize_index_brace
49 |   - php_unit_dedicate_assert
50 |   - php_unit_dedicate_assert_internal_type
51 |   - php_unit_expectation
52 |   - php_unit_mock
53 |   - php_unit_mock_short_will_return
54 |   - php_unit_namespaced
55 |   - php_unit_no_expectation_annotation
56 |   - phpdoc_no_empty_return
57 |   - phpdoc_no_useless_inheritdoc
58 |   - phpdoc_order
59 |   - phpdoc_property
60 |   - phpdoc_scalar
61 |   - phpdoc_singular_inheritdoc
62 |   - phpdoc_trim
63 |   - phpdoc_trim_consecutive_blank_line_separation
64 |   - phpdoc_type_to_var
65 |   - phpdoc_types
66 |   - phpdoc_types_order
67 |   - print_to_echo
68 |   - regular_callable_call
69 |   - return_assignment
70 |   - self_accessor
71 |   - self_static_accessor
72 |   - set_type_to_cast
73 |   - short_array_syntax
74 |   - short_list_syntax
75 |   - simplified_if_return
76 |   - single_quote
77 |   - standardize_not_equals
78 |   - ternary_to_null_coalescing
79 |   - trailing_comma_in_multiline_array
80 |   - unalign_double_arrow
81 |   - unalign_equals
82 |   - empty_loop_body_braces
83 |   - integer_literal_case
84 |   - union_type_without_spaces
85 | 
86 | disabled:
87 |   - function_declaration
88 | 


--------------------------------------------------------------------------------
/composer.json:
--------------------------------------------------------------------------------
 1 | {
 2 |     "name": "yiisoft/bootstrap5",
 3 |     "type": "library",
 4 |     "description": "Yii Framework Twitter Bootstrap 5 Extension",
 5 |     "keywords": [
 6 |         "yii",
 7 |         "bootstrap5"
 8 |     ],
 9 |     "license": "BSD-3-Clause",
10 |     "support": {
11 |         "issues": "https://github.com/yiisoft/bootstrap5/issues?state=open",
12 |         "source": "https://github.com/yiisoft/bootstrap5",
13 |         "forum": "https://www.yiiframework.com/forum/",
14 |         "wiki": "https://www.yiiframework.com/wiki/",
15 |         "irc": "ircs://irc.libera.chat:6697/yii",
16 |         "chat": "https://t.me/yii3en"
17 |     },
18 |     "require": {
19 |         "php": "~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0",
20 |         "yiisoft/html": "^3.0",
21 |         "yiisoft/widget": "^2.0"
22 |     },
23 |     "require-dev": {
24 |         "maglnet/composer-require-checker": "^4.1",
25 |         "phpunit/phpunit": "^10.5",
26 |         "rector/rector": "^2.0",
27 |         "roave/infection-static-analysis-plugin": "^1.35",
28 |         "spatie/phpunit-watcher": "^1.23",
29 |         "vimeo/psalm": "^5.26.1|^6.4.1",
30 |         "yiisoft/aliases": "^3.0",
31 |         "yiisoft/di": "^1.0"
32 |     },
33 |     "suggest": {
34 |         "yiisoft/assets": "Register assets with Yiisoft\\Assets\\AssetManager",
35 |         "yiisoft/files": "Use PathMatcher to filter assets"
36 |     },
37 |     "autoload": {
38 |         "psr-4": {
39 |             "Yiisoft\\Bootstrap5\\": "src"
40 |         }
41 |     },
42 |     "autoload-dev": {
43 |         "psr-4": {
44 |             "Yiisoft\\Bootstrap5\\Tests\\": "tests"
45 |         }
46 |     },
47 |     "config": {
48 |         "sort-packages": true,
49 |         "allow-plugins": {
50 |             "infection/extension-installer": true,
51 |             "composer/package-versions-deprecated": true,
52 |             "composer/installers": true,
53 |             "oomphinc/composer-installers-extender": true
54 |         }
55 |     },
56 |     "repositories": [
57 |         {
58 |             "type": "composer",
59 |             "url": "https://asset-packagist.org"
60 |         }
61 |     ],
62 |     "scripts": {
63 |         "mutation": "vendor/bin/roave-infection-static-analysis-plugin --threads=2 --min-msi=100 --min-covered-msi=100 --ignore-msi-with-no-mutations --only-covered",
64 |         "test": "phpunit --testdox --no-interaction",
65 |         "test-watch": "phpunit-watcher watch"
66 |     }
67 | }
68 | 


--------------------------------------------------------------------------------
/src/Utility/TextColor.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5\Utility;
  6 | 
  7 | /**
  8 |  * Text colors.
  9 |  *
 10 |  * @see https://getbootstrap.com/docs/5.3/utilities/colors/#colors
 11 |  */
 12 | enum TextColor: string
 13 | {
 14 |     /**
 15 |      * Primary text color.
 16 |      */
 17 |     case PRIMARY = 'text-primary';
 18 |     /**
 19 |      * Primary text color with emphasis.
 20 |      */
 21 |     case PRIMARY_EMPHASIS = 'text-primary-emphasis';
 22 |     /**
 23 |      * Secondary text color.
 24 |      */
 25 |     case SECONDARY = 'text-secondary';
 26 |     /**
 27 |      * Secondary text color with emphasis.
 28 |      */
 29 |     case SECONDARY_EMPHASIS = 'text-secondary-emphasis';
 30 |     /**
 31 |      * Success text color.
 32 |      */
 33 |     case SUCCESS = 'text-success';
 34 |     /**
 35 |      * Success text color with emphasis.
 36 |      */
 37 |     case SUCCESS_EMPHASIS = 'text-success-emphasis';
 38 |     /**
 39 |      * Danger text color.
 40 |      */
 41 |     case DANGER = 'text-danger';
 42 |     /**
 43 |      * Danger text color with emphasis.
 44 |      */
 45 |     case DANGER_EMPHASIS = 'text-danger-emphasis';
 46 |     /**
 47 |      * Warning text color.
 48 |      */
 49 |     case WARNING = 'text-warning';
 50 |     /**
 51 |      * Warning text color with emphasis.
 52 |      */
 53 |     case WARNING_EMPHASIS = 'text-warning-emphasis';
 54 |     /**
 55 |      * Info text color.
 56 |      */
 57 |     case INFO = 'text-info';
 58 |     /**
 59 |      * Info text color with emphasis.
 60 |      */
 61 |     case INFO_EMPHASIS = 'text-info-emphasis';
 62 |     /**
 63 |      * Light text color.
 64 |      */
 65 |     case LIGHT = 'text-light';
 66 |     /**
 67 |      * Light text color with emphasis.
 68 |      */
 69 |     case LIGHT_EMPHASIS = 'text-light-emphasis';
 70 |     /**
 71 |      * Dark text color.
 72 |      */
 73 |     case DARK = 'text-dark';
 74 |     /**
 75 |      * Dark text color with emphasis.
 76 |      */
 77 |     case DARK_EMPHASIS = 'text-dark-emphasis';
 78 |     /**
 79 |      * Body text color.
 80 |      */
 81 |     case BODY = 'text-body';
 82 |     /**
 83 |      * Body text color with emphasis.
 84 |      */
 85 |     case BODY_EMPHASIS = 'text-body-emphasis';
 86 |     /**
 87 |      * Secondary body text color.
 88 |      */
 89 |     case BODY_SECONDARY = 'text-body-secondary';
 90 |     /**
 91 |      * Tertiary body text color.
 92 |      */
 93 |     case BODY_TERTIARY = 'text-body-tertiary';
 94 |     /**
 95 |      * Black text color.
 96 |      */
 97 |     case BLACK = 'text-black';
 98 |     /**
 99 |      * White text color.
100 |      */
101 |     case WHITE = 'text-white';
102 | }
103 | 


--------------------------------------------------------------------------------
/src/Utility/BackgroundColor.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5\Utility;
  6 | 
  7 | /**
  8 |  * Background colors.
  9 |  *
 10 |  * @see https://getbootstrap.com/docs/5.3/utilities/background/#background-color
 11 |  */
 12 | enum BackgroundColor: string
 13 | {
 14 |     /**
 15 |      * Black background color.
 16 |      */
 17 |     case BLACK = 'bg-black';
 18 |     /**
 19 |      * White background color.
 20 |      */
 21 |     case BODY = 'bg-body';
 22 |     /**
 23 |      * Secondary body background color.
 24 |      */
 25 |     case BODY_SECONDARY = 'bg-body-secondary';
 26 |     /**
 27 |      * Tertiary body background color.
 28 |      */
 29 |     case BODY_TERTIARY = 'bg-body-tertiary';
 30 |     /**
 31 |      * Dark background color.
 32 |      */
 33 |     case DANGER = 'bg-danger';
 34 |     /**
 35 |      * Subtle dark background color.
 36 |      */
 37 |     case DANGER_SUBTLE = 'bg-danger-subtle';
 38 |     /**
 39 |      * Dark background color.
 40 |      */
 41 |     case DARK = 'bg-dark';
 42 |     /**
 43 |      * Subtle dark background color.
 44 |      */
 45 |     case DARK_SUBTLE = 'bg-dark-subtle';
 46 |     /**
 47 |      * Info background color.
 48 |      */
 49 |     case INFO = 'bg-info';
 50 |     /**
 51 |      * Subtle info background color.
 52 |      */
 53 |     case INFO_SUBTLE = 'bg-info-subtle';
 54 |     /**
 55 |      * Light background color.
 56 |      */
 57 |     case LIGHT = 'bg-light';
 58 |     /**
 59 |      * Subtle light background color.
 60 |      */
 61 |     case LIGHT_SUBTLE = 'bg-light-subtle';
 62 |     /**
 63 |      * Primary background color.
 64 |      */
 65 |     case PRIMARY = 'bg-primary';
 66 |     /**
 67 |      * Subtle primary background color.
 68 |      */
 69 |     case PRIMARY_SUBTLE = 'bg-primary-subtle';
 70 |     /**
 71 |      * Secondary background color.
 72 |      */
 73 |     case SECONDARY = 'bg-secondary';
 74 |     /**
 75 |      * Subtle secondary background color.
 76 |      */
 77 |     case SECONDARY_SUBTLE = 'bg-secondary-subtle';
 78 |     /**
 79 |      * Success background color.
 80 |      */
 81 |     case SUCCESS = 'bg-success';
 82 |     /**
 83 |      * Subtle success background color.
 84 |      */
 85 |     case SUCCESS_SUBTLE = 'bg-success-subtle';
 86 |     /**
 87 |      * Transparent background color.
 88 |      */
 89 |     case TRANSPARENT = 'bg-transparent';
 90 |     /**
 91 |      * Warning background color.
 92 |      */
 93 |     case WARNING = 'bg-warning';
 94 |     /**
 95 |      * Subtle warning background color.
 96 |      */
 97 |     case WARNING_SUBTLE = 'bg-warning-subtle';
 98 |     /**
 99 |      * White background color.
100 |      */
101 |     case WHITE = 'bg-white';
102 | }
103 | 


--------------------------------------------------------------------------------
/src/Utility/AlignItems.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5\Utility;
  6 | 
  7 | /**
  8 |  * Item alignment utilities.
  9 |  *
 10 |  * @see https://getbootstrap.com/docs/5.3/utilities/flex/#align-items
 11 |  */
 12 | enum AlignItems: string
 13 | {
 14 |     /**
 15 |      * Align items at the baseline.
 16 |      */
 17 |     case BASELINE = 'align-items-baseline';
 18 |     /**
 19 |      * Align items at the baseline for lg.
 20 |      */
 21 |     case BASELINE_LG = 'align-items-lg-baseline';
 22 |     /**
 23 |      * Align items at the baseline for md.
 24 |      */
 25 |     case BASELINE_MD = 'align-items-md-baseline';
 26 |     /**
 27 |      * Align items at the baseline for xl.
 28 |      */
 29 |     case BASELINE_XL = 'align-items-xl-baseline';
 30 |     /**
 31 |      * Align items at the baseline for sm.
 32 |      */
 33 |     case BASELINE_SM = 'align-items-sm-baseline';
 34 |     /**
 35 |      * Align items at the baseline for xxl.
 36 |      */
 37 |     case BASELINE_XXL = 'align-items-xxl-baseline';
 38 |     /**
 39 |      * Align items at the center.
 40 |      */
 41 |     case CENTER = 'align-items-center';
 42 |     /**
 43 |      * Align items at the center for lg.
 44 |      */
 45 |     case CENTER_LG = 'align-items-lg-center';
 46 |     /**
 47 |      * Align items at the center for md.
 48 |      */
 49 |     case CENTER_MD = 'align-items-md-center';
 50 |     /**
 51 |      * Align items at the center for sm.
 52 |      */
 53 |     case CENTER_SM = 'align-items-sm-center';
 54 |     /**
 55 |      * Align items at the center for xl.
 56 |      */
 57 |     case CENTER_XL = 'align-items-xl-center';
 58 |     /**
 59 |      * Align items at the center for xxl.
 60 |      */
 61 |     case CENTER_XXL = 'align-items-xxl-center';
 62 |     /**
 63 |      * Align items at the end.
 64 |      */
 65 |     case END = 'align-items-end';
 66 |     /**
 67 |      * Align items at the end for lg.
 68 |      */
 69 |     case END_LG = 'align-items-lg-end';
 70 |     /**
 71 |      * Align items at the end for md.
 72 |      */
 73 |     case END_MD = 'align-items-md-end';
 74 |     /**
 75 |      * Align items at the end for sm.
 76 |      */
 77 |     case END_SM = 'align-items-sm-end';
 78 |     /**
 79 |      * Align items at the end for xl.
 80 |      */
 81 |     case END_XL = 'align-items-xl-end';
 82 |     /**
 83 |      * Align items at the end for xxl.
 84 |      */
 85 |     case END_XXL = 'align-items-xxl-end';
 86 |     /**
 87 |      * Align items at the start.
 88 |      */
 89 |     case START = 'align-items-start';
 90 |     /**
 91 |      * Align items at the start for lg.
 92 |      */
 93 |     case START_LG = 'align-items-lg-start';
 94 |     /**
 95 |      * Align items at the start for md.
 96 |      */
 97 |     case START_MD = 'align-items-md-start';
 98 |     /**
 99 |      * Align items at the start for sm.
100 |      */
101 |     case START_SM = 'align-items-sm-start';
102 |     /**
103 |      * Align items at the start for xl.
104 |      */
105 |     case START_XL = 'align-items-xl-start';
106 |     /**
107 |      * Align items at the start for xxl.
108 |      */
109 |     case START_XXL = 'align-items-xxl-start';
110 |     /**
111 |      * Align items at the stretch.
112 |      */
113 |     case STRETCH = 'align-items-stretch';
114 |     /**
115 |      * Align items at the stretch for lg.
116 |      */
117 |     case STRETCH_LG = 'align-items-lg-stretch';
118 |     /**
119 |      * Align items at the stretch for md.
120 |      */
121 |     case STRETCH_MD = 'align-items-md-stretch';
122 |     /**
123 |      * Align items at the stretch for sm.
124 |      */
125 |     case STRETCH_SM = 'align-items-sm-stretch';
126 |     /**
127 |      * Align items at the stretch for xl.
128 |      */
129 |     case STRETCH_XL = 'align-items-xl-stretch';
130 |     /**
131 |      * Align items at the stretch for xxl.
132 |      */
133 |     case STRETCH_XXL = 'align-items-xxl-stretch';
134 | }
135 | 


--------------------------------------------------------------------------------
/src/BreadcrumbLink.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use Yiisoft\Html\Html;
  8 | 
  9 | /**
 10 |  * BreadcrumbLink represents a single breadcrumb navigation link.
 11 |  *
 12 |  * Each link can be either active or inactive, and can be rendered as a plain text (when active) or as a hyperlink
 13 |  * (when inactive).
 14 |  *
 15 |  * Example:
 16 |  * ```php
 17 |  * // Create a standard link
 18 |  * BreadcrumbLink::to('Home', '/');
 19 |  *
 20 |  * // Create an active link (current page)
 21 |  * BreadcrumbLink::to('Current Page', null, true);
 22 |  *
 23 |  * // Create a link with custom attributes
 24 |  * BreadcrumbLink::to('Link', '/path', false, ['class' => 'custom-link']);
 25 |  * ```
 26 |  */
 27 | final class BreadcrumbLink
 28 | {
 29 |     /**
 30 |      * Use {@see BreadcrumbLink::to()} to create an instance.
 31 |      */
 32 |     private function __construct(
 33 |         private string $label,
 34 |         private string|null $url,
 35 |         private bool $active,
 36 |         private bool $encodeLabel,
 37 |         private array $attributes,
 38 |     ) {
 39 |     }
 40 | 
 41 |     /**
 42 |      * Creates a new {@see BreadcrumbLink} instance.
 43 |      *
 44 |      * @param string $label The label text to display.
 45 |      * @param string|null $url The URL for the link.
 46 |      * @param bool $active Whether this link represents the current page.
 47 |      * @param array $attributes Additional HTML attributes for the link.
 48 |      * @param bool $encodeLabel Whether to HTML encode the label.
 49 |      *
 50 |      * @return self A new instance with the specified configuration.
 51 |      */
 52 |     public static function to(
 53 |         string $label,
 54 |         string|null $url = null,
 55 |         bool $active = false,
 56 |         array $attributes = [],
 57 |         bool $encodeLabel = true
 58 |     ): self {
 59 |         return new self($label, $url, $active, $encodeLabel, $attributes);
 60 |     }
 61 | 
 62 |     /**
 63 |      * Sets the active state.
 64 |      *
 65 |      * @param bool $enabled Whether the breadcrumb link is active.
 66 |      *
 67 |      * @return self A new instance with the specified active state.
 68 |      */
 69 |     public function active(bool $enabled): self
 70 |     {
 71 |         $new = clone $this;
 72 |         $new->active = $enabled;
 73 | 
 74 |         return $new;
 75 |     }
 76 | 
 77 |     /**
 78 |      * Sets the HTML attributes for the link.
 79 |      *
 80 |      * @param array $attributes Attribute values indexed by attribute names.
 81 |      *
 82 |      * @return self A new instance with the specified attributes.
 83 |      *
 84 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
 85 |      */
 86 |     public function attributes(array $attributes): self
 87 |     {
 88 |         $new = clone $this;
 89 |         $new->attributes = $attributes;
 90 | 
 91 |         return $new;
 92 |     }
 93 | 
 94 |     /**
 95 |      * Sets whether to HTML encode the label.
 96 |      *
 97 |      * @param bool $enabled Whether to HTML encode the label.
 98 |      *
 99 |      * @return self A new instance with the specified encoding behavior.
100 |      */
101 |     public function encodeLabel(bool $enabled): self
102 |     {
103 |         $new = clone $this;
104 |         $new->encodeLabel = $enabled;
105 | 
106 |         return $new;
107 |     }
108 | 
109 |     /**
110 |      * Sets the label text to display.
111 |      *
112 |      * @param string $label The label text to display.
113 |      *
114 |      * @return self A new instance with the specified label.
115 |      */
116 |     public function label(string $label): self
117 |     {
118 |         $new = clone $this;
119 |         $new->label = $label;
120 | 
121 |         return $new;
122 |     }
123 | 
124 |     /**
125 |      * Sets the URL for the link.
126 |      *
127 |      * @param string|null $url The URL for the link.
128 |      *
129 |      * @return self A new instance with the specified URL.
130 |      */
131 |     public function url(string|null $url): self
132 |     {
133 |         $new = clone $this;
134 |         $new->url = $url;
135 | 
136 |         return $new;
137 |     }
138 | 
139 |     /**
140 |      * @return array The HTML attributes for the link.
141 |      */
142 |     public function getAttributes(): array
143 |     {
144 |         return $this->attributes;
145 |     }
146 | 
147 |     /**
148 |      * @return string The encoded label content. For default behavior, the label will be HTML-encoded. You can
149 |      * disable this by setting `encodeLabel` to `false`.
150 |      */
151 |     public function getLabel(): string
152 |     {
153 |         return $this->encodeLabel ? Html::encode($this->label) : $this->label;
154 |     }
155 | 
156 |     /**
157 |      * @return string|null The URL for the link.
158 |      */
159 |     public function getUrl(): string|null
160 |     {
161 |         return $this->url;
162 |     }
163 | 
164 |     /**
165 |      * @return bool Whether the item is active.
166 |      */
167 |     public function isActive(): bool
168 |     {
169 |         return $this->active;
170 |     }
171 | }
172 | 


--------------------------------------------------------------------------------
/src/AccordionItem.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use InvalidArgumentException;
  8 | use Yiisoft\Html\Html;
  9 | 
 10 | /**
 11 |  * AccordionItem represents a single collapsible item within an Accordion widget.
 12 |  *
 13 |  * Each item consists of a header that can be clicked to show/hide the body content. The item can be set as active
 14 |  * (expanded) by default and supports both raw and HTML content.
 15 |  *
 16 |  *
 17 |  * For example:
 18 |  *
 19 |  * ```php
 20 |  * AccordionItem::to(
 21 |  *     'Collapsible Group Item #1'
 22 |  *     'Any sufficiently advanced technology is indistinguishable from magic.',
 23 |  * );
 24 |  * ```
 25 |  */
 26 | final class AccordionItem
 27 | {
 28 |     private const DEFAULT_ID_PREFIX = 'collapse';
 29 | 
 30 |     /**
 31 |      * Use {@see AccordionItem::to()} to create a new instance.
 32 |      */
 33 |     private function __construct(
 34 |         private bool $active,
 35 |         private string $body,
 36 |         private bool $encodeBody,
 37 |         private bool $encodeHeader,
 38 |         private string $header,
 39 |         private bool|string $id,
 40 |     ) {
 41 |     }
 42 | 
 43 |     /**
 44 |      * Creates a new {@see AccordionItem} instance.
 45 |      *
 46 |      * @param string $header The header content.
 47 |      * @param string $body The body content.
 48 |      * @param bool|string $id The ID of the accordion item. If `true`, an auto-generated ID will be used. If `false`, no
 49 |      * ID will be set.
 50 |      * @param bool $encodeHeader Whether to encode the header content.
 51 |      * @param bool $encodeBody Whether to encode the body content.
 52 |      * @param bool $active Whether the item is active.
 53 |      *
 54 |      * @return self A new instance with the specified configuration.
 55 |      */
 56 |     public static function to(
 57 |         string $header = '',
 58 |         string $body = '',
 59 |         bool|string $id = true,
 60 |         bool $encodeHeader = true,
 61 |         bool $encodeBody = true,
 62 |         bool $active = false
 63 |     ): self {
 64 |         return new self($active, $body, $encodeBody, $encodeHeader, $header, $id);
 65 |     }
 66 | 
 67 |     /**
 68 |      * Sets the active state.
 69 |      *
 70 |      * @param bool $enabled Whether the accordion item is active.
 71 |      *
 72 |      * @return self A new instance with the specified active state.
 73 |      */
 74 |     public function active(bool $enabled): self
 75 |     {
 76 |         $new = clone $this;
 77 |         $new->active = $enabled;
 78 | 
 79 |         return $new;
 80 |     }
 81 | 
 82 |     /**
 83 |      * Sets the body content.
 84 |      *
 85 |      * @param string $content The body content.
 86 |      *
 87 |      * @return self A new instance with the specified body content.
 88 |      */
 89 |     public function body(string $content): self
 90 |     {
 91 |         $new = clone $this;
 92 |         $new->body = $content;
 93 | 
 94 |         return $new;
 95 |     }
 96 | 
 97 |     /**
 98 |      * Sets whether to encode the body content.
 99 |      *
100 |      * @param bool $enabled Whether to encode the body content.
101 |      *
102 |      * @return self A new instance with the specified encoding setting.
103 |      */
104 |     public function encodeBody(bool $enabled): self
105 |     {
106 |         $new = clone $this;
107 |         $new->encodeBody = $enabled;
108 | 
109 |         return $new;
110 |     }
111 | 
112 |     /**
113 |      * Sets whether to encode the header content.
114 |      *
115 |      * @param bool $enabled Whether to encode the header content.
116 |      *
117 |      * @return self A new instance with the specified encoding setting.
118 |      */
119 |     public function encodeHeader(bool $enabled): self
120 |     {
121 |         $new = clone $this;
122 |         $new->encodeHeader = $enabled;
123 | 
124 |         return $new;
125 |     }
126 | 
127 |     /**
128 |      * Sets the header content.
129 |      *
130 |      * @param string $content The header content.
131 |      *
132 |      * @return self A new instance with the specified header content.
133 |      */
134 |     public function header(string $content): self
135 |     {
136 |         $new = clone $this;
137 |         $new->header = $content;
138 | 
139 |         return $new;
140 |     }
141 | 
142 |     /**
143 |      * Sets the ID.
144 |      *
145 |      * @param bool|string $id The ID of the accordion item. If `true`, an auto-generated ID will be used. If `false`,
146 |      * no ID will be set.
147 |      *
148 |      * @throws InvalidArgumentException If the "id" property is empty or `false`.
149 |      * @return self A new instance with the specified ID.
150 |      */
151 |     public function id(bool|string $id): self
152 |     {
153 |         if ($id === '' || $id === false) {
154 |             throw new InvalidArgumentException('The "id" property must be a non-empty string or `true`.');
155 |         }
156 | 
157 |         $new = clone $this;
158 |         $new->id = $id;
159 | 
160 |         return $new;
161 |     }
162 | 
163 |     /**
164 |      * @return string The encoded header content. If {@see encodeHeader} is `false`, the header content will not be
165 |      * encoded.
166 |      */
167 |     public function getHeader(): string
168 |     {
169 |         return $this->encodeHeader ? Html::encode($this->header) : $this->header;
170 |     }
171 | 
172 |     /**
173 |      * @return string The encoded body content. If {@see encodeBody} is `false`, the body content will not be encoded.
174 |      */
175 |     public function getBody(): string
176 |     {
177 |         return $this->encodeBody ? Html::encode($this->body) : $this->body;
178 |     }
179 | 
180 |     /**
181 |      * Returns the ID.
182 |      *
183 |      * @throws InvalidArgumentException If the "id" property is invalid.
184 |      *
185 |      * @return bool|string The ID.
186 |      */
187 |     public function getId(): bool|string
188 |     {
189 |         return match ($this->id) {
190 |             true => Html::generateId(self::DEFAULT_ID_PREFIX . '-'),
191 |             '', false => throw new InvalidArgumentException('The "id" property must be a non-empty string or `true`.'),
192 |             default => $this->id,
193 |         };
194 |     }
195 | 
196 |     /**
197 |      * @return bool Whether the item is active.
198 |      */
199 |     public function isActive(): bool
200 |     {
201 |         return $this->active;
202 |     }
203 | }
204 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | <p align="center">
  2 |     <a href="https://github.com/yiisoft" target="_blank">
  3 |         <img src="https://yiisoft.github.io/docs/images/yii_logo.svg" height="100px" alt="Yii">
  4 |     </a>
  5 |     <a href="https://getbootstrap.com/" target="_blank">
  6 |         <img src="https://v4-alpha.getbootstrap.com/assets/brand/bootstrap-solid.svg" height="100px" alt="Bootstrap">
  7 |     </a>
  8 |     <h1 align="center">Yii Framework Twitter Bootstrap 5 Extension</h1>
  9 |     <br>
 10 | </p>
 11 | 
 12 | [![Latest Stable Version](https://poser.pugx.org/yiisoft/bootstrap5/v)](https://packagist.org/packages/yiisoft/bootstrap5)
 13 | [![Total Downloads](https://poser.pugx.org/yiisoft/bootstrap5/downloads)](https://packagist.org/packages/yiisoft/bootstrap5)
 14 | [![Build status](https://github.com/yiisoft/bootstrap5/workflows/build/badge.svg)](https://github.com/yiisoft/bootstrap5/actions?query=workflow%3Abuild)
 15 | [![Code coverage](https://codecov.io/gh/yiisoft/bootstrap5/graph/badge.svg?token=S8ISXCPS2A)](https://codecov.io/gh/yiisoft/bootstrap5)
 16 | [![Mutation testing badge](https://img.shields.io/endpoint?style=flat&url=https%3A%2F%2Fbadge-api.stryker-mutator.io%2Fgithub.com%2Fyiisoft%2Fbootstrap5%2Fmaster)](https://dashboard.stryker-mutator.io/reports/github.com/yiisoft/bootstrap5/master)
 17 | [![static analysis](https://github.com/yiisoft/bootstrap5/workflows/static%20analysis/badge.svg)](https://github.com/yiisoft/bootstrap5/actions?query=workflow%3A%22static+analysis%22)
 18 | [![type-coverage](https://shepherd.dev/github/yiisoft/bootstrap5/coverage.svg)](https://shepherd.dev/github/yiisoft/bootstrap5)
 19 | 
 20 | This [Yii Framework] extension encapsulates [Twitter Bootstrap 5] components
 21 | and plugins in terms of Yii widgets, and thus makes using Bootstrap components/plugins
 22 | in Yii applications extremely easy.
 23 | 
 24 | For example, to use the [Bootstrap 5 Carousel](https://getbootstrap.com/docs/5.3/components/carousel/) component, you
 25 | can do the following: 
 26 | 
 27 | ```php
 28 | <?php
 29 | 
 30 | declare(strict_types=1);
 31 | 
 32 | use Yiisoft\Bootstrap5\Carousel;
 33 | use Yiisoft\Bootstrap5\CarouselItem;
 34 | use Yiisoft\Html\Tag\Div;
 35 | use Yiisoft\Html\Tag\H2;
 36 | use Yiisoft\Html\Tag\P;
 37 | 
 38 | ?>
 39 | 
 40 | <?= Carousel::widget()
 41 |     ->id('carouselExampleOnlyText')
 42 |     ->items(
 43 |         CarouselItem::to(
 44 |             Div::tag()
 45 |                 ->addClass('bg-primary text-white p-5 text-center')
 46 |                 ->addContent(
 47 |                     H2::tag()->content('Title 1'),
 48 |                     P::tag()->content('This is the first slide with text.'),
 49 |                 ),
 50 |         ),
 51 |         CarouselItem::to(
 52 |             Div::tag()
 53 |                 ->addClass('bg-success text-white p-5 text-center')
 54 |                 ->addContent(
 55 |                     H2::tag()->content('Title 2'),
 56 |                     P::tag()->content('This is the second slide with text.'),
 57 |                 ),
 58 |         ),
 59 |         CarouselItem::to(
 60 |             Div::tag()
 61 |                 ->addClass('bg-danger text-white p-5 text-center')
 62 |                 ->addContent(
 63 |                     H2::tag()->content('Title 3'),
 64 |                     P::tag()->content('This is the third slide with text.'),
 65 |                 ),
 66 |         ),
 67 |     );
 68 | ```
 69 | 
 70 | ## Requirements
 71 | 
 72 | - PHP 8.1 or higher.
 73 | 
 74 | ## Installation
 75 | 
 76 | The package could be installed with [Composer](https://getcomposer.org):
 77 | 
 78 | ```shell
 79 | composer require yiisoft/bootstrap5
 80 | ```
 81 | 
 82 | ## Install assets
 83 | 
 84 | There are several ways to install the assets, they are:
 85 | 
 86 | 1. Using the [AssetPackagist](https://asset-packagist.org/) package manager.
 87 | 
 88 |     Add to composer.json the following:
 89 |     
 90 |     ```json
 91 |     {
 92 |         "require": {
 93 |             "npm-asset/bootstrap": "^5.3",
 94 |             "oomphinc/composer-installers-extender": "^2.0"
 95 |         },
 96 |         "extra": {
 97 |             "installer-types": [
 98 |                 "npm-asset"
 99 |             ],
100 |             "installer-paths": {
101 |                 "./node_modules/{$name}": [
102 |                     "type:npm-asset"
103 |                 ]
104 |             }
105 |         },
106 |         "repositories": [
107 |             {
108 |                 "type": "composer",
109 |                 "url": "https://asset-packagist.org"
110 |             }
111 |         ]
112 |     }
113 |     ```
114 |     
115 |     Once the changes are made, you can install the assets using the following command:
116 |     
117 |     ```shell
118 |     composer update
119 |     ```
120 | 
121 | 2. Using the [npm-asset](https://www.npmjs.com/) package manager.
122 | 
123 |     Run the following command at the root directory of your application.
124 |     
125 |     ```shell
126 |     npm i bootstrap@5.3.1
127 |     ```
128 | 
129 | ## Using the [yiisoft/assets](https://github.com/yiisoft/assets) package
130 | 
131 | To use the asset classes in the `src/Assets` directory (such as `BootstrapAsset` and `BootstrapCdnAsset`), you need to
132 | install additional packages:
133 |     
134 | ```shell
135 | composer require yiisoft/assets yiisoft/files
136 | ```
137 | 
138 | ## Documentation
139 | 
140 | - [Twitter Bootstrap 5.3](https://getbootstrap.com/docs/5.3/getting-started/introduction/)
141 | - Guide:
142 |   - [English](docs/guide/en/README.md)
143 | - [Internals](docs/internals.md)
144 | 
145 | If you need help or have a question, the [Yii Forum](https://forum.yiiframework.com/c/yii-3-0/63) is a good place for that.
146 | You may also check out other [Yii Community Resources](https://www.yiiframework.com/community).
147 | 
148 | ## License
149 | 
150 | The Yii Framework Twitter Bootstrap 5 Extension is free software. It is released under the terms of the BSD License.
151 | Please see [`LICENSE`](./LICENSE.md) for more information.
152 | 
153 | Maintained by [Yii Software](https://www.yiiframework.com/).
154 | 
155 | ## Support the project
156 | 
157 | [![Open Collective](https://img.shields.io/badge/Open%20Collective-sponsor-7eadf1?logo=open%20collective&logoColor=7eadf1&labelColor=555555)](https://opencollective.com/yiisoft)
158 | 
159 | ## Follow updates
160 | 
161 | [![Official website](https://img.shields.io/badge/Powered_by-Yii_Framework-green.svg?style=flat)](https://www.yiiframework.com/)
162 | [![Twitter](https://img.shields.io/badge/twitter-follow-1DA1F2?logo=twitter&logoColor=1DA1F2&labelColor=555555?style=flat)](https://twitter.com/yiiframework)
163 | [![Telegram](https://img.shields.io/badge/telegram-join-1DA1F2?style=flat&logo=telegram)](https://t.me/yii3en)
164 | [![Facebook](https://img.shields.io/badge/facebook-join-1DA1F2?style=flat&logo=facebook&logoColor=ffffff)](https://www.facebook.com/groups/yiitalk)
165 | [![Slack](https://img.shields.io/badge/slack-join-1DA1F2?style=flat&logo=slack)](https://yiiframework.com/go/slack)
166 | 
167 | [Yii Framework]: https://www.yiiframework.com/
168 | [Twitter Bootstrap 5]: https://getbootstrap.com/docs/5.3/getting-started/introduction/
169 | 


--------------------------------------------------------------------------------
/src/ProgressStack.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use Yiisoft\Html\Html;
  9 | use Yiisoft\Html\Tag\Div;
 10 | use Yiisoft\Widget\Widget;
 11 | 
 12 | /**
 13 |  * The progress stack component allows you to stack multiple progress bars on top of each other.
 14 |  *
 15 |  * For example,
 16 |  *
 17 |  * ```php
 18 |  * echo ProgressStack::widget()
 19 |  *    ->bars(
 20 |  *        Progress::widget()
 21 |  *            ->ariaLabel('Segment one')
 22 |  *            ->id('segment-one')
 23 |  *            ->percent(15),
 24 |  *        Progress::widget()
 25 |  *            ->ariaLabel('Segment two')
 26 |  *            ->backGroundColor(BackgroundColor::SUCCESS)
 27 |  *            ->id('segment-two')
 28 |  *            ->percent(30),
 29 |  *        Progress::widget()
 30 |  *            ->ariaLabel('Segment three')
 31 |  *            ->backGroundColor(BackgroundColor::INFO)
 32 |  *            ->id('segment-three')
 33 |  *            ->percent(20),
 34 |  *    )
 35 |  *    ->render();
 36 |  *
 37 |  * @see https://getbootstrap.com/docs/5.3/components/progress/#multiple-bars
 38 |  */
 39 | final class ProgressStack extends Widget
 40 | {
 41 |     private const NAME = 'progress-stack';
 42 | 
 43 |     private const PROGRESS_STACKED = 'progress-stacked';
 44 | 
 45 |     private array $attributes = [];
 46 | 
 47 |     private array $cssClasses = [];
 48 | 
 49 |     private array $bars = [];
 50 | 
 51 |     private bool|string $id = true;
 52 | 
 53 |     /**
 54 |      * Adds a set of attributes.
 55 |      *
 56 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 57 |      *
 58 |      * @return self A new instance with the specified attributes added.
 59 |      *
 60 |      * Example usage:
 61 |      * ```php
 62 |      * $progressStack->addAttributes(['data-id' => '123']);
 63 |      * ```
 64 |      */
 65 |     public function addAttributes(array $attributes): self
 66 |     {
 67 |         $new = clone $this;
 68 |         $new->attributes = [...$this->attributes, ...$attributes];
 69 | 
 70 |         return $new;
 71 |     }
 72 | 
 73 |     /**
 74 |      * Adds one or more CSS classes to the existing classes.
 75 |      *
 76 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
 77 |      *
 78 |      * @return self A new instance with the specified CSS classes added to existing ones.
 79 |      *
 80 |      * @link https://html.spec.whatwg.org/#classes
 81 |      *
 82 |      * Example usage:
 83 |      * ```php
 84 |      * $progressStack->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
 85 |      * ```
 86 |      */
 87 |     public function addClass(BackedEnum|string|null ...$class): self
 88 |     {
 89 |         $new = clone $this;
 90 |         $new->cssClasses = [...$this->cssClasses, ...$class];
 91 | 
 92 |         return $new;
 93 |     }
 94 | 
 95 |     /**
 96 |      * Adds a CSS style.
 97 |      *
 98 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
 99 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
100 |      * If it is a string, it will be added as is, for example, `color: red`.
101 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
102 |      * appended to the existing one.
103 |      *
104 |      * @return self A new instance with the specified CSS style value added.
105 |      *
106 |      * Example usage:
107 |      * ```php
108 |      * $progressStack->addCssStyle('color: red');
109 |      *
110 |      * // or
111 |      * $progressStack->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
112 |      * ```
113 |      */
114 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
115 |     {
116 |         $new = clone $this;
117 |         Html::addCssStyle($new->attributes, $style, $overwrite);
118 | 
119 |         return $new;
120 |     }
121 | 
122 |     /**
123 |      * Sets attribute value.
124 |      *
125 |      * @param string $name The attribute name.
126 |      * @param mixed $value The attribute value.
127 |      *
128 |      * @return self A new instance with the specified attribute set.
129 |      *
130 |      * Example usage:
131 |      * ```php
132 |      * $progressStack->attribute('data-id', '123');
133 |      * ```
134 |      */
135 |     public function attribute(string $name, mixed $value): self
136 |     {
137 |         $new = clone $this;
138 |         $new->attributes[$name] = $value;
139 | 
140 |         return $new;
141 |     }
142 | 
143 |     /**
144 |      * Sets the HTML attributes.
145 |      *
146 |      * @param array $attributes Attribute values indexed by attribute names.
147 |      *
148 |      * @return self A new instance with the specified attributes.
149 |      *
150 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
151 |      *
152 |      * Example usage:
153 |      * ```php
154 |      * $progressStack->attributes(['data-id' => '123']);
155 |      * ```
156 |      */
157 |     public function attributes(array $attributes): self
158 |     {
159 |         $new = clone $this;
160 |         $new->attributes = $attributes;
161 | 
162 |         return $new;
163 |     }
164 | 
165 |     /**
166 |      * Sets the progress bars to be displayed.
167 |      *
168 |      * @param Progress ...$bars One or more Progress instances to include in the stack.
169 |      *
170 |      * @return self A new instance with the specified bars.
171 |      *
172 |      * Example usage:
173 |      * ```php
174 |      * $progressStack->bars(
175 |      *     Progress::widget()->percent(15)->backgroundColor(BackgroundColor::SUCCESS),
176 |      *     Progress::widget()->percent(30)->backgroundColor(BackgroundColor::INFO)
177 |      * );
178 |      * ```
179 |      */
180 |     public function bars(Progress ...$bars): self
181 |     {
182 |         $new = clone $this;
183 |         $new->bars = $bars;
184 | 
185 |         return $new;
186 |     }
187 | 
188 |     /**
189 |      * Replaces all existing CSS classes with the specified one(s).
190 |      *
191 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
192 |      *
193 |      * @return self A new instance with the specified CSS classes set.
194 |      *
195 |      * Example usage:
196 |      * ```php
197 |      * $progressStack->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
198 |      * ```
199 |      */
200 |     public function class(BackedEnum|string|null ...$class): self
201 |     {
202 |         $new = clone $this;
203 |         $new->cssClasses = $class;
204 | 
205 |         return $new;
206 |     }
207 | 
208 |     /**
209 |      * Sets the ID.
210 |      *
211 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
212 |      *
213 |      * @return self A new instance with the specified ID.
214 |      *
215 |      * Example usage:
216 |      * ```php
217 |      * $progressStack->id('my-id');
218 |      * ```
219 |      */
220 |     public function id(bool|string $id): self
221 |     {
222 |         $new = clone $this;
223 |         $new->id = $id;
224 | 
225 |         return $new;
226 |     }
227 | 
228 |     /**
229 |      * Run the widget.
230 |      *
231 |      * @return string The HTML representation of the element.
232 |      */
233 |     public function render(): string
234 |     {
235 |         if ($this->bars === []) {
236 |             return '';
237 |         }
238 | 
239 |         $attributes = $this->attributes;
240 |         $content = '';
241 |         $classes = $attributes['class'] ?? null;
242 | 
243 |         unset($attributes['class']);
244 | 
245 |         foreach ($this->bars as $bar) {
246 |             $content .= $bar->stacked()->render() . "\n";
247 |         }
248 | 
249 |         return Div::tag()
250 |             ->attributes($attributes)
251 |             ->addClass(
252 |                 self::PROGRESS_STACKED,
253 |                 ...$this->cssClasses,
254 |             )
255 |             ->addClass($classes)
256 |             ->content(
257 |                 "\n",
258 |                 $content,
259 |             )
260 |             ->encode(false)
261 |             ->id($this->getId())
262 |             ->render();
263 |     }
264 | 
265 |     /**
266 |      * Generates the ID.
267 |      *
268 |      * @return string|null The generated ID.
269 |      *
270 |      * @psalm-return non-empty-string|null The generated ID.
271 |      */
272 |     private function getId(): string|null
273 |     {
274 |         return match ($this->id) {
275 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
276 |             '', false => null,
277 |             default => $this->id,
278 |         };
279 |     }
280 | }
281 | 


--------------------------------------------------------------------------------
/src/ButtonToolbar.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use Yiisoft\Html\Html;
  9 | use Yiisoft\Html\Tag\Base\Tag;
 10 | use Yiisoft\Html\Tag\Div;
 11 | use Yiisoft\Widget\Widget;
 12 | 
 13 | use function implode;
 14 | 
 15 | /**
 16 |  * ButtonToolbar Combines sets of button groups into button toolbars for more complex components.
 17 |  * Use utility classes as needed to space out groups, buttons, and more.
 18 |  *
 19 |  * For example,
 20 |  *
 21 |  * ```php
 22 |  * echo ButtonToolbar::widget()
 23 |  *     ->ariaLabel('Toolbar with button groups')
 24 |  *     ->buttonGroups(
 25 |  *         ButtonGroup::widget()
 26 |  *             ->addClass('me-2')
 27 |  *             ->ariaLabel('First group')
 28 |  *             ->buttons(
 29 |  *                 Button::widget()->label('1')->variant(ButtonVariant::PRIMARY),
 30 |  *                 Button::widget()->label('2')->variant(ButtonVariant::PRIMARY),
 31 |  *                 Button::widget()->label('3')->variant(ButtonVariant::PRIMARY),
 32 |  *                 Button::widget()->label('4')->variant(ButtonVariant::PRIMARY),
 33 |  *             ),
 34 |  *         ButtonGroup::widget()
 35 |  *             ->addClass('me-2')
 36 |  *             ->ariaLabel('Second group')
 37 |  *             ->buttons(
 38 |  *                 Button::widget()->label('5'),
 39 |  *                 Button::widget()->label('6'),
 40 |  *                 Button::widget()->label('7'),
 41 |  *             ),
 42 |  *         ButtonGroup::widget()
 43 |  *             ->ariaLabel('Third group')
 44 |  *             ->buttons(
 45 |  *                 Button::widget()->label('8')->variant(ButtonVariant::INFO),
 46 |  *             )
 47 |  *     )
 48 |  *     ->render();
 49 |  * ```
 50 |  *
 51 |  * @link https://getbootstrap.com/docs/5.3/components/button-group/#button-toolbar
 52 |  */
 53 | final class ButtonToolbar extends Widget
 54 | {
 55 |     private const NAME = 'btn-toolbar';
 56 | 
 57 |     private array $attributes = [];
 58 | 
 59 |     /** @psalm-var ButtonGroup[]|Tag[] $buttonGroups */
 60 |     private array $buttonGroups = [];
 61 | 
 62 |     private array $cssClasses = [];
 63 | 
 64 |     private bool|string $id = true;
 65 | 
 66 |     /**
 67 |      * Adds a sets of attributes.
 68 |      *
 69 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 70 |      *
 71 |      * @return self A new instance with the specified attributes added.
 72 |      *
 73 |      * Example usage:
 74 |      * ```php
 75 |      * $buttonToolbar->addAttributes(['data-id' => '123']);
 76 |      * ```
 77 |      */
 78 |     public function addAttributes(array $attributes): self
 79 |     {
 80 |         $new = clone $this;
 81 |         $new->attributes = [...$new->attributes, ...$attributes];
 82 | 
 83 |         return $new;
 84 |     }
 85 | 
 86 |     /**
 87 |      * Adds one or more CSS classes to the existing classes.
 88 |      *
 89 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
 90 |      * automatically.
 91 |      *
 92 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
 93 |      *
 94 |      * @return self A new instance with the specified CSS classes added to existing ones.
 95 |      *
 96 |      * @link https://html.spec.whatwg.org/#classes
 97 |      *
 98 |      * Example usage:
 99 |      * ```php
100 |      * $buttonToolbar->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
101 |      * ```
102 |      */
103 |     public function addClass(BackedEnum|string|null ...$class): self
104 |     {
105 |         $new = clone $this;
106 |         $new->cssClasses = [...$this->cssClasses, ...$class];
107 | 
108 |         return $new;
109 |     }
110 | 
111 |     /**
112 |      * Adds a CSS style.
113 |      *
114 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
115 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
116 |      * If it is a string, it will be added as is, for example, `color: red`.
117 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
118 |      * appended to the existing one.
119 |      *
120 |      * @return self A new instance with the specified CSS style value added.
121 |      *
122 |      * Example usage:
123 |      * ```php
124 |      * $buttonToolbar->addCssStyle('color: red');
125 |      *
126 |      * // or
127 |      * $buttonToolbar->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
128 |      * ```
129 |      */
130 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
131 |     {
132 |         $new = clone $this;
133 |         Html::addCssStyle($new->attributes, $style, $overwrite);
134 | 
135 |         return $new;
136 |     }
137 | 
138 |     /**
139 |      * Sets the ARIA label.
140 |      *
141 |      * @param string $label The ARIA label.
142 |      *
143 |      * @return self A new instance with the specified ARIA label.
144 |      *
145 |      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-label
146 |      *
147 |      * Example usage:
148 |      * ```php
149 |      * $buttonToolbar->ariaLabel('Toolbar with button groups');
150 |      * ```
151 |      */
152 |     public function ariaLabel(string $label): self
153 |     {
154 |         return $this->attribute('aria-label', $label);
155 |     }
156 | 
157 |     /**
158 |      * Adds a sets attribute value.
159 |      *
160 |      * @param string $name The attribute name.
161 |      * @param mixed $value The attribute value.
162 |      *
163 |      * @return self A new instance with the specified attribute added.
164 |      *
165 |      * Example usage:
166 |      * ```php
167 |      * $buttonToolbar->attribute('data-id', '123');
168 |      * ```
169 |      */
170 |     public function attribute(string $name, mixed $value): self
171 |     {
172 |         $new = clone $this;
173 |         $new->attributes[$name] = $value;
174 | 
175 |         return $new;
176 |     }
177 | 
178 |     /**
179 |      * Sets the HTML attributes.
180 |      *
181 |      * @param array $attributes Attribute values indexed by attribute names.
182 |      *
183 |      * @return self A new instance with the specified attributes.
184 |      *
185 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
186 |      *
187 |      * Example usage:
188 |      * ```php
189 |      * $buttonToolbar->attributes(['data-id' => '123']);
190 |      * ```
191 |      */
192 |     public function attributes(array $attributes): self
193 |     {
194 |         $new = clone $this;
195 |         $new->attributes = $attributes;
196 | 
197 |         return $new;
198 |     }
199 | 
200 |     /**
201 |      * List of buttons groups.
202 |      *
203 |      * @param ButtonGroup|Tag ...$groups The button group.
204 |      *
205 |      * @return self A new instance with the specified buttons groups.
206 |      */
207 |     public function buttonGroups(ButtonGroup|Tag ...$groups): self
208 |     {
209 |         $new = clone $this;
210 |         $new->buttonGroups = $groups;
211 | 
212 |         return $new;
213 |     }
214 | 
215 |     /**
216 |      * Replaces all existing CSS classes with the specified one(s).
217 |      *
218 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
219 |      * automatically.
220 |      *
221 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
222 |      *
223 |      * @return self A new instance with the specified CSS classes set.
224 |      *
225 |      * Example usage:
226 |      * ```php
227 |      * $buttonToolbar->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
228 |      * ```
229 |      */
230 |     public function class(BackedEnum|string|null ...$class): self
231 |     {
232 |         $new = clone $this;
233 |         $new->cssClasses = $class;
234 | 
235 |         return $new;
236 |     }
237 | 
238 |     /**
239 |      * Sets the ID.
240 |      *
241 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
242 |      *
243 |      * @return self A new instance with the specified ID.
244 |      *
245 |      * Example usage:
246 |      * ```php
247 |      * $buttonToolbar->id('my-id');
248 |      * ```
249 |      */
250 |     public function id(bool|string $id): self
251 |     {
252 |         $new = clone $this;
253 |         $new->id = $id;
254 | 
255 |         return $new;
256 |     }
257 | 
258 |     /**
259 |      * Run the widget.
260 |      *
261 |      * @return string The HTML representation of the element.
262 |      */
263 |     public function render(): string
264 |     {
265 |         $attributes = $this->attributes;
266 |         $classes = $attributes['class'] ?? null;
267 | 
268 |         unset($attributes['class'], $attributes['id']);
269 | 
270 |         $buttonGroup = implode("\n", $this->buttonGroups);
271 |         $buttonsGroups = $buttonGroup === '' ? '' : "\n" . $buttonGroup . "\n";
272 | 
273 |         if ($buttonsGroups === '') {
274 |             return '';
275 |         }
276 | 
277 |         return Div::tag()
278 |             ->attributes($attributes)
279 |             ->attribute('role', 'toolbar')
280 |             ->addClass(
281 |                 self::NAME,
282 |                 $classes,
283 |                 ...$this->cssClasses,
284 |             )
285 |             ->content($buttonsGroups)
286 |             ->encode(false)
287 |             ->id($this->getId())
288 |             ->render();
289 |     }
290 | 
291 |     /**
292 |      * Generates the ID.
293 |      *
294 |      * @return string|null The generated ID.
295 |      *
296 |      * @psalm-return non-empty-string|null The generated ID.
297 |      */
298 |     private function getId(): string|null
299 |     {
300 |         return match ($this->id) {
301 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
302 |             '', false => null,
303 |             default => $this->id,
304 |         };
305 |     }
306 | }
307 | 


--------------------------------------------------------------------------------
/src/Toggler.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use InvalidArgumentException;
  8 | use Stringable;
  9 | use Yiisoft\Html\Html;
 10 | 
 11 | /**
 12 |  * Toggler represents a single collapsible item within a Bootstrap Collapse component.
 13 |  *
 14 |  * Each item consists of a toggler (button/link) that controls the visibility of collapsible content.
 15 |  * The toggler can be rendered as either a button or link, and can control single or multiple collapse targets.
 16 |  *
 17 |  * Example usage:
 18 |  * ```php
 19 |  * // Basic usage
 20 |  * Toggler::for(
 21 |  *     'Collapsible content here',
 22 |  *     togglerContent: 'Toggle collapse'
 23 |  * );
 24 |  *
 25 |  * // As a link with custom ID
 26 |  * Toggler::for(
 27 |  *     'Collapsible content',
 28 |  *     togglerContent: 'Toggle collapse',
 29 |  *     togglerAsLink: true,
 30 |  *     id: 'customId'
 31 |  * );
 32 |  *
 33 |  * // Multiple collapse control
 34 |  * Toggler::for()
 35 |  *     ->togglerMultiple(true)
 36 |  *     ->ariaControls('collapse1 collapse2')
 37 |  *     ->togglerContent('Toggle multiple collapses');
 38 |  * ```
 39 |  */
 40 | final class Toggler
 41 | {
 42 |     /**
 43 |      * Use {@see Toggler::for()} to create an instance.
 44 |      */
 45 |     private function __construct(
 46 |         private string $content,
 47 |         private string|bool $id,
 48 |         private string $togglerTag,
 49 |         private string $togglerContent,
 50 |         private bool $togglerAsLink,
 51 |         private array $togglerAttributes,
 52 |         private bool $encode,
 53 |         private bool $togglerMultiple,
 54 |         private string $ariaControls,
 55 |     ) {
 56 |     }
 57 | 
 58 |     public static function for(
 59 |         string $content = '',
 60 |         string|bool $id = true,
 61 |         string $togglerTag = 'button',
 62 |         string $togglerContent = '',
 63 |         bool $togglerAsLink = false,
 64 |         array $togglerAttributes = [],
 65 |         bool $encode = true,
 66 |         bool $togglerMultiple = false,
 67 |         string $ariaControls = '',
 68 |     ): self {
 69 |         $new = new self(
 70 |             $content,
 71 |             $id,
 72 |             $togglerTag,
 73 |             $togglerContent,
 74 |             $togglerAsLink,
 75 |             $togglerAttributes,
 76 |             $encode,
 77 |             $togglerMultiple,
 78 |             $ariaControls,
 79 |         );
 80 | 
 81 |         return $new->id($new->getId());
 82 |     }
 83 | 
 84 |     /**
 85 |      * Sets the `aria-controls` attribute value for the toggler.
 86 |      *
 87 |      * @param string $ariaControls The `aria-controls` attribute value for the toggler.
 88 |      *
 89 |      * @return self A new instance with the specified `aria-controls` attribute value for the toggler.
 90 |      */
 91 |     public function ariaControls(string $ariaControls): self
 92 |     {
 93 |         $new = clone $this;
 94 |         $new->ariaControls = $ariaControls;
 95 | 
 96 |         return $new;
 97 |     }
 98 | 
 99 |     /**
100 |      * Sets the content to be displayed in the collapsible item.
101 |      *
102 |      * @param string|Stringable $content The content to be displayed in the collapsible item.
103 |      *
104 |      * @return self A new instance with the specified content to be displayed in the collapsible item.
105 |      */
106 |     public function content(string|Stringable $content): self
107 |     {
108 |         $new = clone $this;
109 |         $new->content = (string)$content;
110 | 
111 |         return $new;
112 |     }
113 | 
114 |     /**
115 |      * Sets whether to HTML encode the content.
116 |      *
117 |      * @param bool $enabled Whether to HTML encode the content.
118 |      *
119 |      * @return self A new instance with the specified encoding behavior.
120 |      */
121 |     public function encode(bool $enabled): self
122 |     {
123 |         $new = clone $this;
124 |         $new->encode = $enabled;
125 | 
126 |         return $new;
127 |     }
128 | 
129 |     /**
130 |      * Generates the ID.
131 |      *
132 |      * @throws InvalidArgumentException if the ID is an empty string or `false`.
133 |      *
134 |      * @return string The generated ID.
135 |      *
136 |      * @psalm-return non-empty-string The generated ID.
137 |      */
138 |     public function getId(): string
139 |     {
140 |         return match ($this->id) {
141 |             true => Html::generateId('collapse-'),
142 |             '', false => throw new InvalidArgumentException('The "id" must be specified.'),
143 |             default => $this->id,
144 |         };
145 |     }
146 | 
147 |     /**
148 |      * Sets the ID.
149 |      *
150 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
151 |      *
152 |      * @throws InvalidArgumentException if the ID is an empty string or `false`.
153 |      *
154 |      * @return self A new instance with the specified ID.
155 |      */
156 |     public function id(bool|string $id): self
157 |     {
158 |         $new = clone $this;
159 |         $new->id = $id;
160 | 
161 |         return $new;
162 |     }
163 | 
164 |     /**
165 |      * @return string The content to be displayed in the collapsible item.
166 |      */
167 |     public function getContent(): string
168 |     {
169 |         return $this->encode ? Html::encode($this->content) : $this->content;
170 |     }
171 | 
172 |     public function getTogglerMultiple(): bool
173 |     {
174 |         return $this->togglerMultiple;
175 |     }
176 | 
177 |     /**
178 |      * Render the toggler to be displayed in the collapsible item.
179 |      *
180 |      * @throws InvalidArgumentException if the toggler tag is an empty string.
181 |      *
182 |      * @return string The HTML representation of the element.
183 |      */
184 |     public function renderToggler(): string
185 |     {
186 |         if ($this->togglerTag === '') {
187 |             throw new InvalidArgumentException('Toggler tag cannot be empty string.');
188 |         }
189 | 
190 |         $tagName = $this->togglerAsLink ? 'a' : $this->togglerTag;
191 | 
192 |         $togglerAttributes = $this->togglerAttributes;
193 |         $togglerClasses = $this->togglerAttributes['class'] ?? 'btn btn-primary';
194 | 
195 |         unset($togglerAttributes['class']);
196 | 
197 |         return Html::tag($tagName, $this->togglerContent)
198 |             ->attribute('type', $tagName === 'button' ? 'button' : null)
199 |             ->attribute('data-bs-toggle', 'collapse')
200 |             ->attribute('data-bs-target', $this->togglerMultiple ? '.multi-collapse' : '#' . $this->id)
201 |             ->attribute('role', $this->togglerAsLink ? 'button' : null)
202 |             ->attribute('aria-expanded', 'false')
203 |             ->attribute('aria-controls', $this->togglerMultiple ? $this->ariaControls : $this->id)
204 |             ->addClass($togglerClasses)
205 |             ->addAttributes($togglerAttributes)
206 |             ->render();
207 |     }
208 | 
209 |     /**
210 |      * Sets whether the toggler should be rendered as a link.
211 |      *
212 |      * @param bool $enabled Whether to render the toggler as a link.
213 |      * When true, render as an `<a>` tag with `role="button"`.
214 |      * When false, renders as the specified `togglerTag` (defaults to `button`).
215 |      *
216 |      * @return self A new instance with the specified toggler as link setting.
217 |      */
218 |     public function togglerAsLink(bool $enabled): self
219 |     {
220 |         $new = clone $this;
221 |         $new->togglerAsLink = $enabled;
222 | 
223 |         return $new;
224 |     }
225 | 
226 |     /**
227 |      * Sets the HTML attributes for the toggler.
228 |      *
229 |      * @param array $attributes Attribute values indexed by attribute names.
230 |      *
231 |      * @return self A new instance with the specified attributes for the toggler.
232 |      *
233 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
234 |      */
235 |     public function togglerAttributes(array $attributes): self
236 |     {
237 |         $new = clone $this;
238 |         $new->togglerAttributes = $attributes;
239 | 
240 |         return $new;
241 |     }
242 | 
243 |     /**
244 |      * Sets the content to be displayed in the toggler.
245 |      *
246 |      * @param string|Stringable $content The content to be displayed in the toggler.
247 |      *
248 |      * @return self A new instance with the specified content to be displayed in the toggler.
249 |      *
250 |      * Example usage:
251 |      * ```php
252 |      * Toggler::to()->togglerContent('Toggle collapse');
253 |      * ```
254 |      */
255 |     public function togglerContent(string|Stringable $content): self
256 |     {
257 |         $new = clone $this;
258 |         $new->togglerContent = (string) $content;
259 | 
260 |         return $new;
261 |     }
262 | 
263 |     /**
264 |      * Sets whether the toggler should control multiple collapse items.
265 |      *
266 |      * @param bool $enabled Whether the toggler should control multiple collapse items.
267 |      * When true, the toggler will target all collapse items with class `.multi-collapse`.
268 |      * When false, the toggler will only target the collapse item with the specified ID.
269 |      *
270 |      * @return self A new instance with the specified toggler multiple setting.
271 |      *
272 |      * Example usage:
273 |      * ```php
274 |      * Toggler::to()->togglerMultiple(true)->ariaControls('collapseOne collapseTwo');
275 |      * ```
276 |      */
277 |     public function togglerMultiple(bool $enabled): self
278 |     {
279 |         $new = clone $this;
280 |         $new->togglerMultiple = $enabled;
281 | 
282 |         return $new;
283 |     }
284 | 
285 |     /**
286 |      * Sets the tag name to be used to render the toggler.
287 |      *
288 |      * @param string $tag The tag name to be used to render the toggler.
289 |      *
290 |      * @throws InvalidArgumentException if the tag name is an empty string.
291 |      *
292 |      * @return self A new instance with the specified tag name to be used to render the toggler.
293 |      *
294 |      * Example usage:
295 |      * ```php
296 |      * Toggler::to()->togglerTag('a');
297 |      * ```
298 |      */
299 |     public function togglerTag(string $tag): self
300 |     {
301 |         $new = clone $this;
302 |         $new->togglerTag = $tag;
303 | 
304 |         return $new;
305 |     }
306 | }
307 | 


--------------------------------------------------------------------------------
/src/ButtonGroup.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use Yiisoft\Html\Html;
  9 | use Yiisoft\Html\Tag\Div;
 10 | use Yiisoft\Html\Tag\Input\Checkbox;
 11 | use Yiisoft\Html\Tag\Input\Radio;
 12 | use Yiisoft\Widget\Widget;
 13 | 
 14 | use function implode;
 15 | 
 16 | /**
 17 |  * ButtonGroup renders a button group bootstrap component.
 18 |  *
 19 |  * For example,
 20 |  *
 21 |  * ```php
 22 |  * <?= ButtonGroup::widget()
 23 |  *         ->addClass('btn-lg')
 24 |  *         ->ariaLabel('Basic example')
 25 |  *         ->buttons(
 26 |  *             Button::widget()->label('Left')->variant(ButtonVariant::PRIMARY),
 27 |  *             Button::widget()->label('Middle')->variant(ButtonVariant::PRIMARY),
 28 |  *             Button::widget()->label('Right')->variant(ButtonVariant::PRIMARY),
 29 |  *         )
 30 |  * ?>
 31 |  * ```
 32 |  *
 33 |  * Pressing on the button should be handled via JavaScript. See the following for details:
 34 |  *
 35 |  * @link https://getbootstrap.com/docs/5.3/components/button-group/
 36 |  */
 37 | final class ButtonGroup extends Widget
 38 | {
 39 |     private const NAME = 'btn-group';
 40 | 
 41 |     private array $attributes = [];
 42 | 
 43 |     /** psalm-var Button[]|Checkbox[]|Radio[] $buttons */
 44 |     private array $buttons = [];
 45 | 
 46 |     private array $cssClasses = [];
 47 | 
 48 |     private bool|string $id = true;
 49 | 
 50 |     /**
 51 |      * Adds a sets of attributes.
 52 |      *
 53 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 54 |      *
 55 |      * @return self A new instance with the specified attributes added.
 56 |      *
 57 |      * Example usage:
 58 |      * ```php
 59 |      * $buttonGroup->addAttributes(['data-id' => '123']);
 60 |      * ```
 61 |      */
 62 |     public function addAttributes(array $attributes): self
 63 |     {
 64 |         $new = clone $this;
 65 |         $new->attributes = [...$this->attributes, ...$attributes];
 66 | 
 67 |         return $new;
 68 |     }
 69 | 
 70 |     /**
 71 |      * Adds one or more CSS classes to the existing classes.
 72 |      *
 73 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
 74 |      * automatically.
 75 |      *
 76 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
 77 |      *
 78 |      * @return self A new instance with the specified CSS classes added to existing ones.
 79 |      *
 80 |      * @link https://html.spec.whatwg.org/#classes
 81 |      *
 82 |      * Example usage:
 83 |      * ```php
 84 |      * $buttonGroup->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
 85 |      * ```
 86 |      */
 87 |     public function addClass(BackedEnum|string|null ...$class): self
 88 |     {
 89 |         $new = clone $this;
 90 |         $new->cssClasses = [...$this->cssClasses, ...$class];
 91 | 
 92 |         return $new;
 93 |     }
 94 | 
 95 |     /**
 96 |      * Adds a CSS style.
 97 |      *
 98 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
 99 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
100 |      * If it is a string, it will be added as is, for example, `color: red`.
101 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
102 |      * appended to the existing one.
103 |      *
104 |      * @return self A new instance with the specified CSS style value added.
105 |      *
106 |      * Example usage:
107 |      * ```php
108 |      * $buttonGroup->addCssStyle('color: red');
109 |      *
110 |      * // or
111 |      * $buttonGroup->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
112 |      * ```
113 |      */
114 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
115 |     {
116 |         $new = clone $this;
117 |         Html::addCssStyle($new->attributes, $style, $overwrite);
118 | 
119 |         return $new;
120 |     }
121 | 
122 |     /**
123 |      * Sets the ARIA label.
124 |      *
125 |      * @param string $label The ARIA label.
126 |      *
127 |      * @return self A new instance with the specified ARIA label.
128 |      *
129 |      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-label
130 |      *
131 |      * Example usage:
132 |      * ```php
133 |      * $buttonGroup->ariaLabel('Basic example');
134 |      * ```
135 |      */
136 |     public function ariaLabel(string $label): self
137 |     {
138 |         return $this->attribute('aria-label', $label);
139 |     }
140 | 
141 |     /**
142 |      * Adds a sets attribute value.
143 |      *
144 |      * @param string $name The attribute name.
145 |      * @param mixed $value The attribute value.
146 |      *
147 |      * @return self A new instance with the specified attribute added.
148 |      *
149 |      * Example usage:
150 |      * ```php
151 |      * $buttonGroup->attribute('data-id', '123');
152 |      * ```
153 |      */
154 |     public function attribute(string $name, mixed $value): self
155 |     {
156 |         $new = clone $this;
157 |         $new->attributes[$name] = $value;
158 | 
159 |         return $new;
160 |     }
161 | 
162 |     /**
163 |      * Sets the HTML attributes.
164 |      *
165 |      * @param array $attributes Attribute values indexed by attribute names.
166 |      *
167 |      * @return self A new instance with the specified attributes.
168 |      *
169 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
170 |      *
171 |      * Example usage:
172 |      * ```php
173 |      * $buttonGroup->attributes(['data-id' => '123']);
174 |      * ```
175 |      */
176 |     public function attributes(array $attributes): self
177 |     {
178 |         $new = clone $this;
179 |         $new->attributes = $attributes;
180 | 
181 |         return $new;
182 |     }
183 | 
184 |     /**
185 |      * List of buttons.
186 |      *
187 |      * @param Button|Checkbox|Radio ...$buttons The button.
188 |      *
189 |      * @return self A new instance with the specified buttons.
190 |      *
191 |      * Example usage:
192 |      * ```php
193 |      * $buttonGroup->buttons(
194 |      *     Button::widget()->label('Left')->variant(ButtonVariant::PRIMARY),
195 |      *     Button::widget()->label('Middle')->variant(ButtonVariant::PRIMARY),
196 |      *     Button::widget()->label('Right')->variant(ButtonVariant::PRIMARY),
197 |      * );
198 |      * ```
199 |      */
200 |     public function buttons(Button|Checkbox|Radio ...$buttons): self
201 |     {
202 |         $new = clone $this;
203 |         $new->buttons = $buttons;
204 | 
205 |         return $new;
206 |     }
207 | 
208 |     /**
209 |      * Replaces all existing CSS classes with the specified one(s).
210 |      *
211 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
212 |      * automatically.
213 |      *
214 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
215 |      *
216 |      * @return self A new instance with the specified CSS classes set.
217 |      *
218 |      * Example usage:
219 |      * ```php
220 |      * $buttonGroup->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
221 |      * ```
222 |      */
223 |     public function class(BackedEnum|string|null ...$class): self
224 |     {
225 |         $new = clone $this;
226 |         $new->cssClasses = $class;
227 | 
228 |         return $new;
229 |     }
230 | 
231 |     /**
232 |      * Sets the ID.
233 |      *
234 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
235 |      *
236 |      * @return self A new instance with the specified ID.
237 |      *
238 |      * Example usage:
239 |      * ```php
240 |      * $buttonGroup->id('my-id');
241 |      * ```
242 |      */
243 |     public function id(bool|string $id): self
244 |     {
245 |         $new = clone $this;
246 |         $new->id = $id;
247 | 
248 |         return $new;
249 |     }
250 | 
251 |     /**
252 |      * Sets the size.
253 |      *
254 |      * @param ButtonSize|null $size The size. If `null`, the size will not be set.
255 |      *
256 |      * @return self A new instance with the specified size.
257 |      *
258 |      * Example usage:
259 |      * ```php
260 |      * $buttonGroup->size(ButtonSize::LARGE);
261 |      * ```
262 |      */
263 |     public function size(ButtonSize|null $size): self
264 |     {
265 |         return $this->addClass($size?->value);
266 |     }
267 | 
268 |     /**
269 |      * Sets the button group to be vertical.
270 |      *
271 |      * @return self A new instance of the current class with the button group as vertical.
272 |      *
273 |      * Example usage:
274 |      * ```php
275 |      * $buttonGroup->vertical();
276 |      * ```
277 |      */
278 |     public function vertical(): self
279 |     {
280 |         return $this->addClass('btn-group-vertical');
281 |     }
282 | 
283 |     /**
284 |      * Run the button group widget.
285 |      *
286 |      * @return string The HTML representation of the element.
287 |      */
288 |     public function render(): string
289 |     {
290 |         $attributes = $this->attributes;
291 |         $classes = $attributes['class'] ?? null;
292 | 
293 |         unset($attributes['class'], $attributes['id']);
294 | 
295 |         $button = implode("\n", $this->buttons);
296 |         $buttons = $button === '' ? '' : "\n" . $button . "\n";
297 | 
298 |         if ($buttons === '') {
299 |             return '';
300 |         }
301 | 
302 |         return Div::tag()
303 |             ->attributes($attributes)
304 |             ->attribute('role', 'group')
305 |             ->addClass(
306 |                 self::NAME,
307 |                 $classes,
308 |                 ...$this->cssClasses,
309 |             )
310 |             ->content($buttons)
311 |             ->encode(false)
312 |             ->id($this->getId())
313 |             ->render();
314 |     }
315 | 
316 |     /**
317 |      * Generates the ID.
318 |      *
319 |      * @return string|null The generated ID.
320 |      *
321 |      * @psalm-return non-empty-string|null The generated ID.
322 |      */
323 |     private function getId(): string|null
324 |     {
325 |         return match ($this->id) {
326 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
327 |             '', false => null,
328 |             default => $this->id,
329 |         };
330 |     }
331 | }
332 | 


--------------------------------------------------------------------------------
/src/CarouselItem.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use Stringable;
  8 | use Yiisoft\Html\Html;
  9 | 
 10 | /**
 11 |  * CarouselItem represents a single item within a Bootstrap Carousel widget.
 12 |  *
 13 |  * Each item can contain content, caption, and caption placeholder.
 14 |  *
 15 |  * The item can be set as active and supports autoplaying intervals.
 16 |  *
 17 |  * - Active state: When is `true`, sets this item as the first visible slide.
 18 |  * - Auto-playing: When enabled, cycling can be paused by hovering over the carousel, focusing on it, or clicking
 19 |  * on carousel controls/indicators.
 20 |  *
 21 |  * Example usage:
 22 |  * ```php
 23 |  * <?= CarouselItem::to(
 24 |  *         '<img src="example.jpg" alt="Example">',
 25 |  *         'Image Caption',
 26 |  *         'Caption Placeholder'
 27 |  *     );
 28 |  * ?>
 29 |  *
 30 |  * // Create an active carousel item with autoplay.
 31 |  * <?= CarouselItem::to(
 32 |  *         content: '<img src="example.jpg">',
 33 |  *         caption: 'Slide 1',
 34 |  *         active: true,
 35 |  *         autoPlayingInterval: 5000
 36 |  *     );
 37 |  * ?>
 38 |  * ```
 39 |  */
 40 | final class CarouselItem
 41 | {
 42 |     /**
 43 |      * Use {@see CarouselItem::to()} to create a new instance.
 44 |      */
 45 |     private function __construct(
 46 |         private bool $active,
 47 |         private array $attributes,
 48 |         private int|null $autoPlayingInterval,
 49 |         private string|null $caption,
 50 |         private array $captionAttributes,
 51 |         private string|null $captionPlaceholder,
 52 |         private array $captionPlaceholderAttributes,
 53 |         private string|Stringable $content,
 54 |         private bool $encodeCaption,
 55 |         private bool $encodeCaptionPlaceholder,
 56 |     ) {
 57 |     }
 58 | 
 59 |     /**
 60 |      * Creates a new {@see CarouselItem} instance.
 61 |      *
 62 |      * @param string|Stringable $content The content of the carousel item.
 63 |      * @param string|null $caption The caption content for the carousel item.
 64 |      * @param string|null $captionPlaceholder The caption placeholder content for the carousel item.
 65 |      * @param int|null $autoPlayingInterval The autoplaying interval for the carousel item.
 66 |      * @param bool $active Whether the item is active.
 67 |      * @param bool $encodeCaption Whether to encode the caption content.
 68 |      * @param bool $encodeCaptionPlaceholder Whether to encode the caption placeholder content.
 69 |      * @param array $attributes The HTML attributes for the carousel item.
 70 |      * @param array $captionAttributes The HTML attributes for the caption.
 71 |      * @param array $captionPlaceholderAttributes The HTML attributes for the caption placeholder.
 72 |      *
 73 |      * @return self A new instance with the specified configuration.
 74 |      */
 75 |     public static function to(
 76 |         string|Stringable $content = '',
 77 |         string|null $caption = null,
 78 |         string|null $captionPlaceholder = null,
 79 |         int|null $autoPlayingInterval = null,
 80 |         bool $active = false,
 81 |         bool $encodeCaption = true,
 82 |         bool $encodeCaptionPlaceholder = true,
 83 |         array $attributes = [],
 84 |         array $captionAttributes = [],
 85 |         array $captionPlaceholderAttributes = [],
 86 |     ): self {
 87 |         return new self(
 88 |             $active,
 89 |             $attributes,
 90 |             $autoPlayingInterval,
 91 |             $caption,
 92 |             $captionAttributes,
 93 |             $captionPlaceholder,
 94 |             $captionPlaceholderAttributes,
 95 |             $content,
 96 |             $encodeCaption,
 97 |             $encodeCaptionPlaceholder,
 98 |         );
 99 |     }
100 | 
101 |     /**
102 |      * Sets the active state.
103 |      *
104 |      * @param bool $enabled Whether the breadcrumb link is active.
105 |      *
106 |      * @return self A new instance with the specified active state.
107 |      */
108 |     public function active(bool $enabled): self
109 |     {
110 |         $new = clone $this;
111 |         $new->active = $enabled;
112 | 
113 |         return $new;
114 |     }
115 | 
116 |     /**
117 |      * Sets the HTML attributes for the link.
118 |      *
119 |      * @param array $attributes Attribute values indexed by attribute names.
120 |      *
121 |      * @return self A new instance with the specified attributes.
122 |      *
123 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
124 |      */
125 |     public function attributes(array $attributes): self
126 |     {
127 |         $new = clone $this;
128 |         $new->attributes = $attributes;
129 | 
130 |         return $new;
131 |     }
132 | 
133 |     /**
134 |      * Sets the autoplaying interval.
135 |      *
136 |      * @param int $interval The autoplaying interval in milliseconds.
137 |      *
138 |      * @return self A new instance with the specified autoplaying interval.
139 |      */
140 |     public function autoPlayingInterval(int $interval): self
141 |     {
142 |         $new = clone $this;
143 |         $new->autoPlayingInterval = $interval;
144 | 
145 |         return $new;
146 |     }
147 | 
148 |     /**
149 |      * Sets the caption content.
150 |      *
151 |      * @param string $caption The caption content.
152 |      *
153 |      * @return self A new instance with the specified caption content.
154 |      */
155 |     public function caption(string $caption): self
156 |     {
157 |         $new = clone $this;
158 |         $new->caption = $caption;
159 | 
160 |         return $new;
161 |     }
162 | 
163 |     /**
164 |      * Sets the HTML attributes for the caption.
165 |      *
166 |      * @param array $captionAttributes Attribute values indexed by attribute names.
167 |      *
168 |      * @return self A new instance with the specified attributes for the caption.
169 |      *
170 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
171 |      */
172 |     public function captionAttributes(array $captionAttributes): self
173 |     {
174 |         $new = clone $this;
175 |         $new->captionAttributes = $captionAttributes;
176 | 
177 |         return $new;
178 |     }
179 | 
180 |     /**
181 |      * Sets the caption placeholder content.
182 |      *
183 |      * @param string $captionPlaceholder The caption placeholder content.
184 |      *
185 |      * @return self A new instance with the specified caption placeholder content.
186 |      */
187 |     public function captionPlaceholder(string $captionPlaceholder): self
188 |     {
189 |         $new = clone $this;
190 |         $new->captionPlaceholder = $captionPlaceholder;
191 | 
192 |         return $new;
193 |     }
194 | 
195 |     /**
196 |      * Sets the HTML attributes for the caption placeholder.
197 |      *
198 |      * @param array $captionPlaceholderAttributes Attribute values indexed by attribute names.
199 |      *
200 |      * @return self A new instance with the specified attributes for the caption placeholder.
201 |      *
202 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
203 |      */
204 |     public function captionPlaceholderAttributes(array $captionPlaceholderAttributes): self
205 |     {
206 |         $new = clone $this;
207 |         $new->captionPlaceholderAttributes = $captionPlaceholderAttributes;
208 | 
209 |         return $new;
210 |     }
211 | 
212 |     /**
213 |      * Sets the content.
214 |      *
215 |      * @param string|Stringable $content The content.
216 |      *
217 |      * @return self A new instance with the specified content.
218 |      */
219 |     public function content(string|Stringable $content): self
220 |     {
221 |         $new = clone $this;
222 |         $new->content = $content;
223 | 
224 |         return $new;
225 |     }
226 | 
227 |     /**
228 |      * Sets whether to encode the caption content.
229 |      *
230 |      * @param bool $encode Whether to encode the caption content.
231 |      *
232 |      * @return self A new instance with the specified encoding setting.
233 |      */
234 |     public function encodeCaption(bool $encode): self
235 |     {
236 |         $new = clone $this;
237 |         $new->encodeCaption = $encode;
238 | 
239 |         return $new;
240 |     }
241 | 
242 |     /**
243 |      * Sets whether to encode the caption placeholder content.
244 |      *
245 |      * @param bool $encode Whether to encode the caption placeholder content.
246 |      *
247 |      * @return self A new instance with the specified encoding setting.
248 |      */
249 |     public function encodeCaptionPlaceholder(bool $encode): self
250 |     {
251 |         $new = clone $this;
252 |         $new->encodeCaptionPlaceholder = $encode;
253 | 
254 |         return $new;
255 |     }
256 | 
257 |     /**
258 |      * @return array Returns the HTML attributes for the carousel item.
259 |      */
260 |     public function getAttributes(): array
261 |     {
262 |         return $this->attributes;
263 |     }
264 | 
265 |     /**
266 |      * @return int|null Returns the autoplaying interval for the carousel item.
267 |      */
268 |     public function getAutoPlayingInterval(): int|null
269 |     {
270 |         return $this->autoPlayingInterval;
271 |     }
272 | 
273 |     /**
274 |      * @return string|null Returns the caption content for the carousel item.
275 |      */
276 |     public function getCaption(): string|null
277 |     {
278 |         return $this->encodeCaption ? Html::encode($this->caption) : $this->caption;
279 |     }
280 | 
281 |     /**
282 |      * @return array Returns the HTML attributes for the caption.
283 |      */
284 |     public function getCaptionAttributes(): array
285 |     {
286 |         return $this->captionAttributes;
287 |     }
288 | 
289 |     /**
290 |      * @return string|null Returns the caption placeholder content for the carousel item.
291 |      */
292 |     public function getCaptionPlaceholder(): string|null
293 |     {
294 |         return $this->encodeCaptionPlaceholder ? Html::encode($this->captionPlaceholder) : $this->captionPlaceholder;
295 |     }
296 | 
297 |     /**
298 |      * @return array Returns the HTML attributes for the caption placeholder.
299 |      */
300 |     public function getCaptionPlaceholderAttributes(): array
301 |     {
302 |         return $this->captionPlaceholderAttributes;
303 |     }
304 | 
305 |     /**
306 |      * @return string|Stringable Returns the content for the carousel item.
307 |      */
308 |     public function getContent(): string|Stringable
309 |     {
310 |         return $this->content;
311 |     }
312 | 
313 |     /**
314 |      * @return bool Whether the item is active.
315 |      */
316 |     public function isActive(): bool
317 |     {
318 |         return $this->active;
319 |     }
320 | }
321 | 


--------------------------------------------------------------------------------
/src/NavLink.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use InvalidArgumentException;
  8 | use Stringable;
  9 | use Yiisoft\Html\Html;
 10 | 
 11 | /**
 12 |  * NavLink represents a navigation link item in a Bootstrap Nav component.
 13 |  *
 14 |  * Each NavLink can be either active, disabled, or a regular link. The label can be either a string or a Stringable
 15 |  * object, and can be optionally encoded.
 16 |  *
 17 |  * Example:
 18 |  * ```php
 19 |  * // Create a standard nav link
 20 |  * NavLink::to('Home', '/');
 21 |  *
 22 |  * // Create an active nav link
 23 |  * NavLink::to('Current Page', '#', true);
 24 |  *
 25 |  * // Create a disabled nav link
 26 |  * NavLink::to('Disabled', '#', false, true);
 27 |  *
 28 |  * // Create a tab with content
 29 |  * NavLink::tab('Tab 1', 'Content 1');
 30 |  *
 31 |  * // Create an active tab with content
 32 |  * NavLink::tab('Tab 2', 'Content 2', true);
 33 |  * ```
 34 |  */
 35 | final class NavLink
 36 | {
 37 |     /**
 38 |      * Use {@see NavLink::to()} to create an instance.
 39 |      */
 40 |     private function __construct(
 41 |         private bool $active = false,
 42 |         private array $attributes = [],
 43 |         private bool $encodeLabel = true,
 44 |         private bool $encodeContent = true,
 45 |         private bool $disabled = false,
 46 |         private string|Stringable $label = '',
 47 |         private string|null $url = '',
 48 |         private array $urlAttributes = [],
 49 |         private bool $visible = true,
 50 |         private string|Stringable $content = '',
 51 |         private bool|string $paneId = false,
 52 |         private array $paneAttributes = [],
 53 |     ) {
 54 |     }
 55 | 
 56 |     /**
 57 |      * Creates a {@see NavLink} instance.
 58 |      *
 59 |      * @param string|Stringable $label The label of the link.
 60 |      * @param string|null $url The URL of the link.
 61 |      * @param bool $active Whether the link is active.
 62 |      * @param bool $disabled Whether the link is disabled.
 63 |      * @param bool $encodeLabel Whether the label should be encoded.
 64 |      * @param array $attributes The HTML attributes for the nav item.
 65 |      * @param array $urlAttributes The HTML attributes for the nav item link.
 66 |      * @param bool $visible Whether the nav item is visible.
 67 |      *
 68 |      * @throws InvalidArgumentException If the link is both active and disabled.
 69 |      *
 70 |      * @return self A new instance with the specified attributes.
 71 |      */
 72 |     public static function to(
 73 |         string|Stringable $label = '',
 74 |         string|null $url = null,
 75 |         bool $active = false,
 76 |         bool $disabled = false,
 77 |         bool $encodeLabel = true,
 78 |         array $attributes = [],
 79 |         array $urlAttributes = [],
 80 |         bool $visible = true,
 81 |     ): self {
 82 |         if ($active && $disabled) {
 83 |             throw new InvalidArgumentException('A nav link cannot be both active and disabled.');
 84 |         }
 85 | 
 86 |         return new self(
 87 |             active: $active,
 88 |             attributes: $attributes,
 89 |             encodeLabel: $encodeLabel,
 90 |             disabled: $disabled,
 91 |             label: $label,
 92 |             url: $url,
 93 |             urlAttributes: $urlAttributes,
 94 |             visible: $visible,
 95 |         );
 96 |     }
 97 | 
 98 |     /**
 99 |      * Creates a {@see NavLink} instance for a tab.
100 |      *
101 |      * @param string|Stringable $label The label of the tab.
102 |      * @param string|Stringable $content The content of the tab pane.
103 |      * @param bool $active Whether the tab is active.
104 |      * @param bool $encodeLabel Whether the label should be encoded.
105 |      * @param bool $encodeContent Whether the content should be encoded.
106 |      * @param array $attributes The HTML attributes for the nav item.
107 |      * @param array $urlAttributes The HTML attributes for the nav item link.
108 |      * @param array $paneAttributes The HTML attributes for the tab pane.
109 |      * @param bool $visible Whether the nav item is visible.
110 |      *
111 |      * @throws InvalidArgumentException If the tab is both active and disabled.
112 |      *
113 |      * @return self A new instance with the specified attributes.
114 |      */
115 |     public static function tab(
116 |         string|Stringable $label,
117 |         string|Stringable $content,
118 |         bool $active = false,
119 |         bool $encodeLabel = true,
120 |         bool $encodeContent = true,
121 |         array $attributes = [],
122 |         array $urlAttributes = [],
123 |         bool|string $paneId = true,
124 |         array $paneAttributes = [],
125 |         bool $visible = true,
126 |     ): self {
127 |         return new self(
128 |             active: $active,
129 |             attributes: $attributes,
130 |             encodeLabel: $encodeLabel,
131 |             encodeContent: $encodeContent,
132 |             label: $label,
133 |             url: '#',
134 |             urlAttributes: $urlAttributes,
135 |             visible: $visible,
136 |             content: $content,
137 |             paneId: $paneId,
138 |             paneAttributes: $paneAttributes,
139 |         );
140 |     }
141 | 
142 |     /**
143 |      * Sets the active state of the nav item.
144 |      *
145 |      * @param bool $enabled Whether the nav item is active.
146 |      *
147 |      * @return self A new instance with the specified active state.
148 |      */
149 |     public function active(bool $enabled): self
150 |     {
151 |         $new = clone $this;
152 |         $new->active = $enabled;
153 | 
154 |         return $new;
155 |     }
156 | 
157 |     /**
158 |      * Sets the HTML attributes for the nav item.
159 |      *
160 |      * @param array $attributes Attribute values indexed by attribute names.
161 |      *
162 |      * @return self A new instance with the specified attributes.
163 |      *
164 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
165 |      */
166 |     public function attributes(array $attributes): self
167 |     {
168 |         $new = clone $this;
169 |         $new->attributes = $attributes;
170 | 
171 |         return $new;
172 |     }
173 | 
174 |     /**
175 |      * Sets the content of the tab pane.
176 |      *
177 |      * @param string|Stringable $content The content of the tab pane.
178 |      *
179 |      * @return self A new instance with the specified content.
180 |      */
181 |     public function content(string|Stringable $content): self
182 |     {
183 |         $new = clone $this;
184 |         $new->content = $content;
185 | 
186 |         return $new;
187 |     }
188 | 
189 |     /**
190 |      * Sets the disabled state of the nav item.
191 |      *
192 |      * @param bool $disabled Whether the nav item is disabled.
193 |      *
194 |      * @return self A new instance with the specified disabled state.
195 |      */
196 |     public function disabled(bool $disabled): self
197 |     {
198 |         $new = clone $this;
199 |         $new->disabled = $disabled;
200 | 
201 |         return $new;
202 |     }
203 | 
204 |     /**
205 |      * Sets weather to HTML-encode the content.
206 |      *
207 |      * @param bool $enabled Whether to encode the content.
208 |      *
209 |      * @return self New instance with the specified encoded setting.
210 |      */
211 |     public function encodeContent(bool $enabled): self
212 |     {
213 |         $new = clone $this;
214 |         $new->encodeContent = $enabled;
215 | 
216 |         return $new;
217 |     }
218 | 
219 |     /**
220 |      * Sets weather to HTML-encode the label.
221 |      *
222 |      * @param bool $enabled Whether to encode the label.
223 |      *
224 |      * @return self New instance with the specified encoded setting.
225 |      */
226 |     public function encodeLabel(bool $enabled): self
227 |     {
228 |         $new = clone $this;
229 |         $new->encodeLabel = $enabled;
230 | 
231 |         return $new;
232 |     }
233 | 
234 |     /**
235 |      * @return string|Stringable The content of the tab pane.
236 |      */
237 |     public function getContent(): string|Stringable
238 |     {
239 |         return $this->content;
240 |     }
241 | 
242 |     public function getId(): string
243 |     {
244 |         /** @psalm-var non-empty-string|null $id */
245 |         return match ($this->paneId) {
246 |             true => $this->paneAttributes['id'] ?? Html::generateId('pane'),
247 |             '', false => throw new InvalidArgumentException('The tab pane ID must be specified.'),
248 |             default => $this->paneId,
249 |         };
250 |     }
251 | 
252 |     /**
253 |      * @return string|Stringable The label of Stringable object.
254 |      */
255 |     public function getLabel(): string|Stringable
256 |     {
257 |         return $this->label;
258 |     }
259 | 
260 |     /**
261 |      * @return array The HTML attributes for the tab pane.
262 |      */
263 |     public function getPaneAttributes(): array
264 |     {
265 |         return $this->paneAttributes;
266 |     }
267 | 
268 |     /**
269 |      * @return string|null The URL of the nav item.
270 |      */
271 |     public function getUrl(): string|null
272 |     {
273 |         return $this->url;
274 |     }
275 | 
276 |     /**
277 |      * @return array The HTML attributes for the nav item link.
278 |      */
279 |     public function getUrlAttributes(): array
280 |     {
281 |         return $this->urlAttributes;
282 |     }
283 | 
284 |     /**
285 |      * @return bool Whether the nav item has content.
286 |      */
287 |     public function hasContent(): bool
288 |     {
289 |         return $this->content !== '';
290 |     }
291 | 
292 |     /**
293 |      * Sets the ID of the nav component.
294 |      *
295 |      * @param bool|string $id The ID of the alert component. If `true`, an ID will be generated automatically.
296 |      *
297 |      * @return self A new instance with the specified ID.
298 |      */
299 |     public function paneId(bool|string $id): self
300 |     {
301 |         $new = clone $this;
302 |         $new->paneId = $id;
303 | 
304 |         return $new;
305 |     }
306 | 
307 |     /**
308 |      * Sets the label text for the nav item.
309 |      *
310 |      * @param string|Stringable $label The label text or Stringable object
311 |      *
312 |      * @return self New instance with the specified label text.
313 |      */
314 |     public function label(string|Stringable $label): self
315 |     {
316 |         $new = clone $this;
317 |         $new->label = $label;
318 | 
319 |         return $new;
320 |     }
321 | 
322 |     /**
323 |      * Sets the HTML attributes for the tab pane.
324 |      *
325 |      * @param array $attributes Attribute values indexed by attribute names.
326 |      *
327 |      * @return self New instance with the specified pane attributes.
328 |      *
329 |      * @see Html::renderTagAttributes() for details on how attributes are rendered.
330 |      */
331 |     public function paneAttributes(array $attributes): self
332 |     {
333 |         $new = clone $this;
334 |         $new->paneAttributes = $attributes;
335 | 
336 |         return $new;
337 |     }
338 | 
339 |     /**
340 |      * Sets the URL for the nav item.
341 |      *
342 |      * @param string|null $url The URL or `null` for no URL.
343 |      *
344 |      * @return self New instance with the specified URL.
345 |      */
346 |     public function url(string|null $url): self
347 |     {
348 |         $new = clone $this;
349 |         $new->url = $url;
350 | 
351 |         return $new;
352 |     }
353 | 
354 |     /**
355 |      * Sets HTML attributes for the nav item link.
356 |      *
357 |      * @param array $attributes Attribute values indexed by attribute names.
358 |      *
359 |      * @return self New instance with the specified link attributes.
360 |      *
361 |      * @see Html::renderTagAttributes() for details on how attributes are rendered.
362 |      */
363 |     public function urlAttributes(array $attributes): self
364 |     {
365 |         $new = clone $this;
366 |         $new->urlAttributes = $attributes;
367 | 
368 |         return $new;
369 |     }
370 | 
371 |     /**
372 |      * Sets the visibility of the nav item.
373 |      *
374 |      * @param bool $enabled Whether the nav item is visible.
375 |      *
376 |      * @return self A new instance with the specified visibility.
377 |      */
378 |     public function visible(bool $enabled): self
379 |     {
380 |         $new = clone $this;
381 |         $new->visible = $enabled;
382 | 
383 |         return $new;
384 |     }
385 | 
386 |     /**
387 |      * @return array The HTML attributes for the nav item.
388 |      */
389 |     public function getAttributes(): array
390 |     {
391 |         return $this->attributes;
392 |     }
393 | 
394 |     /**
395 |      * @return bool Whether the nav item is active.
396 |      */
397 |     public function isActive(): bool
398 |     {
399 |         return $this->active;
400 |     }
401 | 
402 |     /**
403 |      * @return bool Whether the nav item is disabled.
404 |      */
405 |     public function isDisabled(): bool
406 |     {
407 |         return $this->disabled;
408 |     }
409 | 
410 |     /**
411 |      * @return bool Whether the nav item is visible.
412 |      */
413 |     public function isVisible(): bool
414 |     {
415 |         return $this->visible;
416 |     }
417 | 
418 |     /**
419 |      * @return bool Whether the content should be encoded.
420 |      */
421 |     public function shouldEncodeContent(): bool
422 |     {
423 |         return $this->encodeContent;
424 |     }
425 | 
426 |     /**
427 |      * @return bool Whether the label should be encoded.
428 |      */
429 |     public function shouldEncodeLabel(): bool
430 |     {
431 |         return $this->encodeLabel;
432 |     }
433 | }
434 | 


--------------------------------------------------------------------------------
/src/DropdownItem.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use Stringable;
  8 | use InvalidArgumentException;
  9 | 
 10 | /**
 11 |  * DropdownItem represents a single item within a Bootstrap Dropdown menu.
 12 |  *
 13 |  * Supports multiple item types:
 14 |  * - Buttons: Button-style menu items.
 15 |  * - Dividers: Horizontal separators.
 16 |  * - Headers: Section headers.
 17 |  * - Links: Standard clickable menu items.
 18 |  * - Text: Plain text items.
 19 |  *
 20 |  * Example usage:
 21 |  * ```php
 22 |  * // Create a link item
 23 |  * DropdownItem::link('Profile', '/profile');
 24 |  *
 25 |  * // Create an active item
 26 |  * DropdownItem::link('Dashboard', '/dashboard', true);
 27 |  *
 28 |  * // Create a divider
 29 |  * DropdownItem::divider();
 30 |  *
 31 |  * // Create a header
 32 |  * DropdownItem::header('Section Title');
 33 |  * ```
 34 |  */
 35 | final class DropdownItem
 36 | {
 37 |     /**
 38 |      * Use {@see DropdownItem::button()} to create a new button instance.
 39 |      * Use {@see DropdownItem::divider()} to create a new divider instance.
 40 |      * Use {@see DropdownItem::header()} to create a new header instance.
 41 |      * Use {@see DropdownItem::link()} to create a new link instance.
 42 |      * Use {@see DropdownItem::text()} to create a new text instance.
 43 |      *
 44 |      * @psalm-param non-empty-string $headerTag
 45 |      */
 46 |     private function __construct(
 47 |         private DropdownItemType $type,
 48 |         private string|Stringable $content,
 49 |         private string $url,
 50 |         private bool $active,
 51 |         private bool $disabled,
 52 |         private array $attributes,
 53 |         private array $itemAttributes,
 54 |         private string $headerTag,
 55 |     ) {
 56 |     }
 57 | 
 58 |     /**
 59 |      * Creates a button-type dropdown item.
 60 |      *
 61 |      * @param string|Stringable $content The button content.
 62 |      * @param array $attributes The HTML attributes for the `<li>` tag.
 63 |      * @param array $itemAttributes The HTML attributes for the `<button>` tag.
 64 |      *
 65 |      * @throws InvalidArgumentException When item is set as both active and disabled.
 66 |      *
 67 |      * @return self A new instance with the specified configuration.
 68 |      *
 69 |      * Example:
 70 |      * ```php
 71 |      * DropdownItem::button('Submit', active: true);
 72 |      * ```
 73 |      */
 74 |     public static function button(
 75 |         string|Stringable $content = '',
 76 |         array $attributes = [],
 77 |         array $itemAttributes = [],
 78 |     ): self {
 79 |         return new self(
 80 |             DropdownItemType::BUTTON,
 81 |             $content,
 82 |             '',
 83 |             false,
 84 |             false,
 85 |             $attributes,
 86 |             $itemAttributes,
 87 |             'h6',
 88 |         );
 89 |     }
 90 | 
 91 |     /**
 92 |      * Creates a divider dropdown item.
 93 |      *
 94 |      * @param array $attributes The HTML attributes for the `<li>` tag.
 95 |      * @param array $itemAttributes The HTML attributes for the `<hr>` tag.
 96 |      *
 97 |      * @return self A new instance with the specified configuration.
 98 |      *
 99 |      * Example:
100 |      * ```php
101 |      * DropdownItem::divider();
102 |      * ```
103 |      */
104 |     public static function divider(array $attributes = [], array $itemAttributes = []): self
105 |     {
106 |         return new self(
107 |             DropdownItemType::DIVIDER,
108 |             '',
109 |             '',
110 |             false,
111 |             false,
112 |             $attributes,
113 |             $itemAttributes,
114 |             'h6',
115 |         );
116 |     }
117 | 
118 |     /**
119 |      * Creates a header dropdown item.
120 |      *
121 |      * @param string|Stringable $content The header text.
122 |      * @param string $headerTag The HTML tag to use (defaults to `h6`).
123 |      * @param array $attributes The HTML attributes for the `<li>` tag.
124 |      * @param array $itemAttributes The HTML attributes for the `<h6>` tag.
125 |      *
126 |      * @throws InvalidArgumentException When header tag is empty.
127 |      *
128 |      * @return self A new instance with the specified configuration.
129 |      *
130 |      * Example:
131 |      * ```php
132 |      * DropdownItem::header('Section Title');
133 |      * ```
134 |      */
135 |     public static function header(
136 |         string|Stringable $content = '',
137 |         string $headerTag = 'h6',
138 |         array $attributes = [],
139 |         array $itemAttributes = [],
140 |     ): self {
141 |         if ($headerTag === '') {
142 |             throw new InvalidArgumentException('The header tag cannot be empty.');
143 |         }
144 | 
145 |         return new self(
146 |             DropdownItemType::HEADER,
147 |             $content,
148 |             '',
149 |             false,
150 |             false,
151 |             $attributes,
152 |             $itemAttributes,
153 |             $headerTag,
154 |         );
155 |     }
156 | 
157 |     /**
158 |      * Creates a link-type dropdown item.
159 |      *
160 |      * @param string|Stringable $content The link text.
161 |      * @param string $url The URL (defaults to '#').
162 |      * @param bool $active Whether the link is active.
163 |      * @param bool $disabled Whether the link is disabled.
164 |      * @param array $attributes The HTML attributes for the `<li>` tag.
165 |      * @param array $itemAttributes The HTML attributes for the `<a>` tag.
166 |      *
167 |      * @throws InvalidArgumentException When item is set as both active and disabled.
168 |      *
169 |      * @return self A new instance with the specified configuration.
170 |      *
171 |      * Example:
172 |      * ```php
173 |      * DropdownItem::link('Profile', '/profile');
174 |      * ```
175 |      */
176 |     public static function link(
177 |         string|Stringable $content = '',
178 |         string $url = '#',
179 |         bool $active = false,
180 |         bool $disabled = false,
181 |         array $attributes = [],
182 |         array $itemAttributes = [],
183 |     ): self {
184 |         if ($active && $disabled) {
185 |             throw new InvalidArgumentException('The dropdown item cannot be active and disabled at the same time.');
186 |         }
187 | 
188 |         return new self(
189 |             DropdownItemType::LINK,
190 |             $content,
191 |             $url,
192 |             $active,
193 |             $disabled,
194 |             $attributes,
195 |             $itemAttributes,
196 |             'h6',
197 |         );
198 |     }
199 | 
200 |     /**
201 |      * Creates a list with custom content dropdown item.
202 |      *
203 |      * @param string|Stringable $content The list content.
204 |      * @param array $attributes The HTML attributes for the `<li>` tag.
205 |      *
206 |      * @return self A new instance with the specified configuration.
207 |      *
208 |      * Example:
209 |      * ```php
210 |      * DropdownItem::listContent('Simple list item');
211 |      * ```
212 |      */
213 |     public static function listContent(string|Stringable $content = '', array $attributes = []): self
214 |     {
215 |         return new self(
216 |             DropdownItemType::CUSTOM_CONTENT,
217 |             $content,
218 |             '',
219 |             false,
220 |             false,
221 |             $attributes,
222 |             [],
223 |             'h6',
224 |         );
225 |     }
226 | 
227 |     /**
228 |      * Creates a text dropdown item.
229 |      *
230 |      * @param string|Stringable $content The text content.
231 |      * @param array $attributes The HTML attributes for the `<li>` tag.
232 |      * @param array $itemAttributes The HTML attributes for the `<span>` tag.
233 |      *
234 |      * @return self A new instance with the specified configuration.
235 |      *
236 |      * Example:
237 |      * ```php
238 |      * DropdownItem::text('Simple text item');
239 |      * ```
240 |      */
241 |     public static function text(
242 |         string|Stringable $content = '',
243 |         array $attributes = [],
244 |         array $itemAttributes = [],
245 |     ): self {
246 |         return new self(
247 |             DropdownItemType::TEXT,
248 |             $content,
249 |             '',
250 |             false,
251 |             false,
252 |             $attributes,
253 |             $itemAttributes,
254 |             'h6',
255 |         );
256 |     }
257 | 
258 |     /**
259 |      * Sets the active state.
260 |      *
261 |      * @param bool $enabled Whether is active or not.
262 |      *
263 |      * @return self A new instance with the specified active state.
264 |      */
265 |     public function active(bool $enabled): self
266 |     {
267 |         if ($enabled && $this->disabled) {
268 |             throw new InvalidArgumentException('The dropdown item cannot be active and disabled at the same time.');
269 |         }
270 | 
271 |         $new = clone $this;
272 |         $new->active = $enabled;
273 | 
274 |         return $new;
275 |     }
276 | 
277 |     /**
278 |      * Sets the HTML attributes.
279 |      *
280 |      * @param array $attributes Attribute values indexed by attribute names.
281 |      *
282 |      * @return self A new instance with the specified attributes.
283 |      *
284 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
285 |      */
286 |     public function attributes(array $attributes): self
287 |     {
288 |         $new = clone $this;
289 |         $new->attributes = $attributes;
290 | 
291 |         return $new;
292 |     }
293 | 
294 |     /**
295 |      * Sets the disabled state.
296 |      *
297 |      * @param bool $enabled Whether is disabled or not.
298 |      *
299 |      * @return self A new instance with the specified disabled state.
300 |      */
301 |     public function disabled(bool $enabled): self
302 |     {
303 |         if ($enabled && $this->active) {
304 |             throw new InvalidArgumentException('The dropdown item cannot be active and disabled at the same time.');
305 |         }
306 | 
307 |         $new = clone $this;
308 |         $new->disabled = $enabled;
309 | 
310 |         return $new;
311 |     }
312 | 
313 |     /**
314 |      * Sets the content.
315 |      *
316 |      * @param string|Stringable $content The content.
317 |      *
318 |      * @return self A new instance with the specified content.
319 |      */
320 |     public function content(string|Stringable $content): self
321 |     {
322 |         $new = clone $this;
323 |         $new->content = $content;
324 | 
325 |         return $new;
326 |     }
327 | 
328 |     /**
329 |      * @return array The HTML attributes for the `<li>` tag.
330 |      */
331 |     public function getAttributes(): array
332 |     {
333 |         return $this->attributes;
334 |     }
335 | 
336 |     /**
337 |      * @return string|Stringable The content.
338 |      */
339 |     public function getContent(): string|Stringable
340 |     {
341 |         return $this->content;
342 |     }
343 | 
344 |     /**
345 |      * @return string The header tag.
346 |      *
347 |      * @psalm-return non-empty-string
348 |      */
349 |     public function getHeaderTag(): string
350 |     {
351 |         return $this->headerTag;
352 |     }
353 | 
354 |     /**
355 |      * @return array The HTML attributes for the item.
356 |      */
357 |     public function getItemAttributes(): array
358 |     {
359 |         return $this->itemAttributes;
360 |     }
361 | 
362 |     /**
363 |      * @return string The URL.
364 |      */
365 |     public function getUrl(): string
366 |     {
367 |         return $this->url;
368 |     }
369 | 
370 |     /**
371 |      * @return DropdownItemType The type.
372 |      */
373 |     public function getType(): DropdownItemType
374 |     {
375 |         return $this->type;
376 |     }
377 | 
378 |     /**
379 |      * Sets the header tag.
380 |      *
381 |      * @param string $tag The header tag.
382 |      *
383 |      * @return self A new instance with the specified header tag.
384 |      */
385 |     public function headerTag(string $tag): self
386 |     {
387 |         if ($tag === '') {
388 |             throw new InvalidArgumentException('The header tag cannot be empty.');
389 |         }
390 | 
391 |         $new = clone $this;
392 |         $new->headerTag = $tag;
393 | 
394 |         return $new;
395 |     }
396 | 
397 |     /**
398 |      * @return bool Whether the item is active.
399 |      */
400 |     public function isActive(): bool
401 |     {
402 |         return $this->active;
403 |     }
404 | 
405 |     /**
406 |      * @return bool Whether the item is disabled.
407 |      */
408 |     public function isDisabled(): bool
409 |     {
410 |         return $this->disabled;
411 |     }
412 | 
413 |     /**
414 |      * Sets the HTML attributes for the item.
415 |      *
416 |      * @param array $attributes Attribute values indexed by attribute names.
417 |      *
418 |      * @return self A new instance with the specified attributes for the item.
419 |      *
420 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
421 |      */
422 |     public function itemAttributes(array $attributes): self
423 |     {
424 |         $new = clone $this;
425 |         $new->itemAttributes = $attributes;
426 | 
427 |         return $new;
428 |     }
429 | 
430 |     /**
431 |      * Sets the type.
432 |      *
433 |      * @param DropdownItemType $type The type.
434 |      *
435 |      * @return self A new instance with the specified type.
436 |      */
437 |     public function type(DropdownItemType $type): self
438 |     {
439 |         $new = clone $this;
440 |         $new->type = $type;
441 | 
442 |         return $new;
443 |     }
444 | 
445 |     /**
446 |      * Sets the URL.
447 |      *
448 |      * @param string $url The URL.
449 |      *
450 |      * @return self A new instance with the specified URL.
451 |      */
452 |     public function url(string $url): self
453 |     {
454 |         $new = clone $this;
455 |         $new->url = $url;
456 | 
457 |         return $new;
458 |     }
459 | }
460 | 


--------------------------------------------------------------------------------
/src/Collapse.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use InvalidArgumentException;
  9 | use Yiisoft\Html\Html;
 10 | use Yiisoft\Html\Tag\Div;
 11 | use Yiisoft\Widget\Widget;
 12 | 
 13 | use function count;
 14 | use function implode;
 15 | 
 16 | /**
 17 |  * Collapse renders a Bootstrap collapse component.
 18 |  *
 19 |  * For example:
 20 |  *
 21 |  * ```php
 22 |  * <?= Collapse::widget()
 23 |  *         ->containerAttributes(['class' => 'row'])
 24 |  *         ->items(
 25 |  *             Toggler::to(
 26 |  *                 'Some placeholder content for the first collapse component of this multi-collapse example. ' .
 27 |  *                 'This panel is hidden by default but revealed when the user activates the relevant trigger.',
 28 |  *                 'multiCollapseExample1',
 29 |  *                 togglerContent: 'Toggle first element',
 30 |  *                 togglerAsLink: true,
 31 |  *             ),
 32 |  *             Toggler::to(
 33 |  *                 'Some placeholder content for the second collapse component of this multi-collapse example. ' .
 34 |  *                 'This panel is hidden by default but revealed when the user activates the relevant trigger.',
 35 |  *                 'multiCollapseExample2',
 36 |  *                 togglerContent: 'Toggle second element',
 37 |  *             ),
 38 |  *             Toggler::to(
 39 |  *                 togglerContent: 'Toggle both elements',
 40 |  *                 togglerMultiple: true,
 41 |  *                 ariaControls: 'multiCollapseExample1 multiCollapseExample2',
 42 |  *             ),
 43 |  *         )
 44 |  * ?>
 45 |  * ```
 46 |  *
 47 |  * @link https://getbootstrap.com/docs/5.3/components/collapse/
 48 |  */
 49 | final class Collapse extends Widget
 50 | {
 51 |     private const NAME = 'collapse';
 52 | 
 53 |     private const CARD = 'card';
 54 | 
 55 |     private const CARD_BODY = 'card-body';
 56 | 
 57 |     private const COLLAPSE_MULTIPLE = 'multi-collapse';
 58 | 
 59 |     private array $attributes = [];
 60 | 
 61 |     private array $cardBodyAttributes = [];
 62 | 
 63 |     private bool $container = true;
 64 | 
 65 |     private array $containerAttributes = [];
 66 | 
 67 |     private array $cssClasses = [];
 68 | 
 69 |     /** @var Toggler[] */
 70 |     private array $items = [];
 71 | 
 72 |     private string $togglerContainerTag = 'p';
 73 | 
 74 |     private array $togglerContainerAttributes = [];
 75 | 
 76 |     /**
 77 |      * Adds a sets of attributes.
 78 |      *
 79 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 80 |      *
 81 |      * @return self A new instance with the specified attributes added.
 82 |      *
 83 |      * Example usage:
 84 |      * ```php
 85 |      * $collapse->addAttributes(['data-id' => '123']);
 86 |      * ```
 87 |      */
 88 |     public function addAttributes(array $attributes): self
 89 |     {
 90 |         $new = clone $this;
 91 |         $new->attributes = [...$this->attributes, ...$attributes];
 92 | 
 93 |         return $new;
 94 |     }
 95 | 
 96 |     /**
 97 |      * Adds one or more CSS classes to the existing classes.
 98 |      *
 99 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
100 |      * automatically.
101 |      *
102 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
103 |      *
104 |      * @return self A new instance with the specified CSS classes added to existing ones.
105 |      *
106 |      * @link https://html.spec.whatwg.org/#classes
107 |      *
108 |      * Example usage:
109 |      * ```php
110 |      * $collapse->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
111 |      * ```
112 |      */
113 |     public function addClass(BackedEnum|string|null ...$class): self
114 |     {
115 |         $new = clone $this;
116 |         $new->cssClasses = [...$this->cssClasses, ...$class];
117 | 
118 |         return $new;
119 |     }
120 | 
121 |     /**
122 |      * Adds a CSS style.
123 |      *
124 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
125 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
126 |      * If it is a string, it will be added as is, for example, `color: red`.
127 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
128 |      * appended to the existing one.
129 |      *
130 |      * @return self A new instance with the specified CSS style value added.
131 |      *
132 |      * Example usage:
133 |      * ```php
134 |      * $collapse->addCssStyle('color: red');
135 |      *
136 |      * // or
137 |      * $collapse->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
138 |      * ```
139 |      */
140 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
141 |     {
142 |         $new = clone $this;
143 |         Html::addCssStyle($new->attributes, $style, $overwrite);
144 | 
145 |         return $new;
146 |     }
147 | 
148 |     /**
149 |      * Adds a sets attribute value.
150 |      *
151 |      * @param string $name The attribute name.
152 |      * @param mixed $value The attribute value.
153 |      *
154 |      * @return self A new instance with the specified attribute added.
155 |      *
156 |      * Example usage:
157 |      * ```php
158 |      * $collapse->attribute('data-id', '123');
159 |      * ```
160 |      */
161 |     public function attribute(string $name, mixed $value): self
162 |     {
163 |         $new = clone $this;
164 |         $new->attributes[$name] = $value;
165 | 
166 |         return $new;
167 |     }
168 | 
169 |     /**
170 |      * Sets the HTML attributes.
171 |      *
172 |      * @param array $attributes Attribute values indexed by attribute names.
173 |      *
174 |      * @return self A new instance with the specified attributes.
175 |      *
176 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
177 |      *
178 |      * Example usage:
179 |      * ```php
180 |      * $collapse->attributes(['data-id' => '123']);
181 |      * ```
182 |      */
183 |     public function attributes(array $attributes): self
184 |     {
185 |         $new = clone $this;
186 |         $new->attributes = $attributes;
187 | 
188 |         return $new;
189 |     }
190 | 
191 |     /**
192 |      * Sets the HTML attributes for the card body.
193 |      *
194 |      * @param array $attributes Attribute values indexed by attribute names.
195 |      *
196 |      * @return self A new instance with the specified attributes for the card body.
197 |      *
198 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
199 |      *
200 |      * Example usage:
201 |      * ```php
202 |      * $collapse->cardBodyAttributes(['data-id' => '123']);
203 |      * ```
204 |      */
205 |     public function cardBodyAttributes(array $attributes): self
206 |     {
207 |         $new = clone $this;
208 |         $new->cardBodyAttributes = $attributes;
209 | 
210 |         return $new;
211 |     }
212 | 
213 |     /**
214 |      * Replaces all existing CSS classes with the specified one(s).
215 |      *
216 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
217 |      * automatically.
218 |      *
219 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
220 |      *
221 |      * @return self A new instance with the specified CSS classes set.
222 |      *
223 |      * Example usage:
224 |      * ```php
225 |      * $collapse->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
226 |      * ```
227 |      */
228 |     public function class(BackedEnum|string|null ...$class): self
229 |     {
230 |         $new = clone $this;
231 |         $new->cssClasses = $class;
232 | 
233 |         return $new;
234 |     }
235 | 
236 |     /**
237 |      * Sets the container for the collapse items.
238 |      *
239 |      * @param bool $enabled Whether to wrap the collapse items in a container.
240 |      *
241 |      * @return self A new instance with the specified container.
242 |      *
243 |      * Example usage:
244 |      * ```php
245 |      * $collapse->container(true);
246 |      * ```
247 |      */
248 |     public function container(bool $enabled): self
249 |     {
250 |         $new = clone $this;
251 |         $new->container = $enabled;
252 | 
253 |         return $new;
254 |     }
255 | 
256 |     /**
257 |      * Sets the HTML attributes for the container of the collapse items.
258 |      *
259 |      * @param array $attributes Attribute values indexed by attribute names.
260 |      *
261 |      * @return self A new instance with the specified attributes for the container of the collapse items.
262 |      *
263 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
264 |      *
265 |      * Example usage:
266 |      * ```php
267 |      * $collapse->containerAttributes(['data-id' => '123']);
268 |      * ```
269 |      */
270 |     public function containerAttributes(array $attributes): self
271 |     {
272 |         $new = clone $this;
273 |         $new->containerAttributes = $attributes;
274 | 
275 |         return $new;
276 |     }
277 | 
278 |     /**
279 |      * Sets the items.
280 |      *
281 |      * @param Toggler ...$items The items.
282 |      *
283 |      * @return self A new instance with the specified items.
284 |      *
285 |      * Example usage:
286 |      * ```php
287 |      * $collapse->items(
288 |      *     Toggler::widget('Item 1'),
289 |      *     Toggler::widget()->content('Item 2'),
290 |      * );
291 |      * ```
292 |      */
293 |     public function items(Toggler ...$items): self
294 |     {
295 |         $new = clone $this;
296 |         $new->items = $items;
297 | 
298 |         return $new;
299 |     }
300 | 
301 |     /**
302 |      * Sets the HTML attributes for the container of the toggler.
303 |      *
304 |      * @param array $attributes Attribute values indexed by attribute names.
305 |      *
306 |      * @return self A new instance with the specified attributes for the container of the toggler.
307 |      *
308 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
309 |      *
310 |      * Example usage:
311 |      * ```php
312 |      * $collapse->togglerContainerAttributes(['data-id' => '123']);
313 |      * ```
314 |      */
315 |     public function togglerContainerAttributes(array $attributes): self
316 |     {
317 |         $new = clone $this;
318 |         $new->togglerContainerAttributes = $attributes;
319 | 
320 |         return $new;
321 |     }
322 | 
323 |     /**
324 |      * Sets the tag for the container of the toggler.
325 |      *
326 |      * @param string $tag The tag for the container of the toggler.
327 |      *
328 |      * @return self A new instance with the specified tag for the container of the toggler.
329 |      *
330 |      * Example usage:
331 |      * ```php
332 |      * $collapse->togglerContainerTag('div');
333 |      * ```
334 |      */
335 |     public function togglerContainerTag(string $tag): self
336 |     {
337 |         $new = clone $this;
338 |         $new->togglerContainerTag = $tag;
339 | 
340 |         return $new;
341 |     }
342 | 
343 |     /**
344 |      * Run the widget.
345 |      *
346 |      * @return string The HTML representation of the element.
347 |      */
348 |     public function render(): string
349 |     {
350 |         if ($this->items === []) {
351 |             return '';
352 |         }
353 | 
354 |         $collapse = [];
355 |         $isMultiple = count($this->items) > 1;
356 |         $toggler = [];
357 | 
358 |         foreach ($this->items as $item) {
359 |             if ($item->getContent() !== '') {
360 |                 $collapseDiv = Div::tag()
361 |                     ->addClass(self::NAME, ...$this->cssClasses)
362 |                     ->addAttributes($this->attributes)
363 |                     ->addContent(
364 |                         "\n",
365 |                         Div::tag()
366 |                             ->addAttributes($this->cardBodyAttributes)
367 |                             ->addClass(self::CARD, self::CARD_BODY)
368 |                             ->addContent(
369 |                                 "\n",
370 |                                 $item->getContent(),
371 |                                 "\n"
372 |                             ),
373 |                         "\n"
374 |                     )
375 |                     ->id($item->getId());
376 | 
377 |                 if ($isMultiple) {
378 |                     $collapseDiv = $collapseDiv->addClass(self::COLLAPSE_MULTIPLE);
379 | 
380 |                     if ($item->getTogglerMultiple() === false) {
381 |                         $collapse[] = Div::tag()->addClass('col')->addContent("\n", $collapseDiv, "\n");
382 |                     }
383 |                 } else {
384 |                     $collapse[] = $collapseDiv;
385 |                 }
386 |             }
387 | 
388 |             $toggler[] = $item->renderToggler();
389 |         }
390 | 
391 |         return $this->renderTogglerContainer($toggler) . "\n" . $this->renderCollapse($collapse);
392 |     }
393 | 
394 |     /**
395 |      * Renders the collapse.
396 |      *
397 |      * @param array $collapse The collapse.
398 |      *
399 |      * @return string The HTML representation of the element.
400 |      */
401 |     private function renderCollapse(array $collapse): string
402 |     {
403 |         $collapseContent = implode("\n", $collapse);
404 | 
405 |         return $this->container
406 |             ? Div::tag()
407 |                 ->addAttributes($this->containerAttributes)
408 |                 ->addContent("\n", $collapseContent, "\n")
409 |                 ->encode(false)
410 |                 ->render()
411 |             : $collapseContent;
412 |     }
413 | 
414 |     /**
415 |      * Renders the toggler container.
416 |      *
417 |      * @param array $toggler The toggler.
418 |      *
419 |      * @return string The HTML representation of the element.
420 |      */
421 |     private function renderTogglerContainer(array $toggler): string
422 |     {
423 |         if ($this->togglerContainerTag === '') {
424 |             throw new InvalidArgumentException('Toggler container tag cannot be empty string.');
425 |         }
426 | 
427 |         return Html::tag($this->togglerContainerTag)
428 |             ->addAttributes($this->togglerContainerAttributes)
429 |             ->addContent("\n", implode("\n", $toggler), "\n")
430 |             ->encode(false)
431 |             ->render();
432 |     }
433 | }
434 | 


--------------------------------------------------------------------------------
/src/Progress.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use LogicException;
  9 | use Yiisoft\Bootstrap5\Utility\BackgroundColor;
 10 | use Yiisoft\Bootstrap5\Utility\Sizing;
 11 | use Yiisoft\Html\Html;
 12 | use Yiisoft\Html\Tag\Div;
 13 | use Yiisoft\Widget\Widget;
 14 | 
 15 | use function sprintf;
 16 | 
 17 | /**
 18 |  * Progress renders a bootstrap progress bar component.
 19 |  *
 20 |  * For example,
 21 |  *
 22 |  * ```php
 23 |  * <?= Progress::widget()->percent(60) ?>
 24 |  *
 25 |  * //
 26 |  *
 27 |  * <?= Progress::widget()
 28 |  *     ->backgroundColor(BackgroundColor::SUCCESS)
 29 |  *     ->percent(60)
 30 |  *     ->variant(ProgressVariant::ANIMATED_STRIPED)
 31 |  * ?>
 32 |  * ```
 33 |  *
 34 |  * @link https://getbootstrap.com/docs/5.3/components/progress/
 35 |  */
 36 | final class Progress extends Widget
 37 | {
 38 |     private const NAME = 'progress';
 39 | 
 40 |     private const PROGRESS_BAR = 'progress-bar';
 41 | 
 42 |     private array $attributes = [];
 43 | 
 44 |     private array $barAttributes = [];
 45 | 
 46 |     private array $barClasses = [];
 47 | 
 48 |     private array $cssClasses = [];
 49 | 
 50 |     private string $content = '';
 51 | 
 52 |     private bool|string $id = true;
 53 | 
 54 |     private int|float $max = 100;
 55 | 
 56 |     private int|float $min = 0;
 57 | 
 58 |     private int|float $percent = 0;
 59 | 
 60 |     private bool $sizing = false;
 61 | 
 62 |     private bool $stacked = false;
 63 | 
 64 |     /**
 65 |      * Adds a set of attributes.
 66 |      *
 67 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 68 |      *
 69 |      * @return self A new instance with the specified attributes added.
 70 |      *
 71 |      * Example usage:
 72 |      * ```php
 73 |      * $progress->addAttributes(['data-id' => '123']);
 74 |      * ```
 75 |      */
 76 |     public function addAttributes(array $attributes): self
 77 |     {
 78 |         $new = clone $this;
 79 |         $new->attributes = [...$this->attributes, ...$attributes];
 80 | 
 81 |         return $new;
 82 |     }
 83 | 
 84 |     /**
 85 |      * Adds one or more CSS classes for the bar.
 86 |      *
 87 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add to the bar. Pass `null` to skip adding a class.
 88 |      *
 89 |      * @return self A new instance with the specified CSS classes added to the bar.
 90 |      *
 91 |      * Example usage:
 92 |      * ```php
 93 |      * $progress->addBarClass('bg-success', null, 'progress-bar-striped');
 94 |      * ```
 95 |      */
 96 |     public function addBarClass(BackedEnum|string|null ...$class): self
 97 |     {
 98 |         $new = clone $this;
 99 |         $new->barClasses = [...$this->barClasses, ...$class];
100 | 
101 |         return $new;
102 |     }
103 | 
104 |     /**
105 |      * Adds one or more CSS classes to the existing classes.
106 |      *
107 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
108 |      *
109 |      * @return self A new instance with the specified CSS classes added to existing ones.
110 |      *
111 |      * @link https://html.spec.whatwg.org/#classes
112 |      *
113 |      * Example usage:
114 |      * ```php
115 |      * $progress->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
116 |      * ```
117 |      */
118 |     public function addClass(BackedEnum|string|null ...$class): self
119 |     {
120 |         $new = clone $this;
121 |         $new->cssClasses = [...$this->cssClasses, ...$class];
122 | 
123 |         return $new;
124 |     }
125 | 
126 |     /**
127 |      * Adds a CSS style.
128 |      *
129 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
130 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
131 |      * If it is a string, it will be added as is, for example, `color: red`.
132 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
133 |      * appended to the existing one.
134 |      *
135 |      * @return self A new instance with the specified CSS style value added.
136 |      *
137 |      * Example usage:
138 |      * ```php
139 |      * $progress->addCssStyle('color: red');
140 |      *
141 |      * // or
142 |      * $progress->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
143 |      * ```
144 |      */
145 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
146 |     {
147 |         $new = clone $this;
148 |         Html::addCssStyle($new->attributes, $style, $overwrite);
149 | 
150 |         return $new;
151 |     }
152 | 
153 |     /**
154 |      * Sets the ARIA label.
155 |      *
156 |      * @param string $label The ARIA label.
157 |      *
158 |      * @return self A new instance with the specified ARIA label.
159 |      *
160 |      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-label
161 |      *
162 |      * Example usage:
163 |      * ```php
164 |      * $progress->ariaLabel('breadcrumb');
165 |      * ```
166 |      */
167 |     public function ariaLabel(string $label): self
168 |     {
169 |         return $this->attribute('aria-label', $label);
170 |     }
171 | 
172 |     /**
173 |      * Sets attribute value.
174 |      *
175 |      * @param string $name The attribute name.
176 |      * @param mixed $value The attribute value.
177 |      *
178 |      * @return self A new instance with the specified attribute set.
179 |      *
180 |      * Example usage:
181 |      * ```php
182 |      * $progress->attribute('data-id', '123');
183 |      * ```
184 |      */
185 |     public function attribute(string $name, mixed $value): self
186 |     {
187 |         $new = clone $this;
188 |         $new->attributes[$name] = $value;
189 | 
190 |         return $new;
191 |     }
192 | 
193 |     /**
194 |      * Sets the HTML attributes.
195 |      *
196 |      * @param array $attributes Attribute values indexed by attribute names.
197 |      *
198 |      * @return self A new instance with the specified attributes.
199 |      *
200 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
201 |      *
202 |      * Example usage:
203 |      * ```php
204 |      * $progress->attributes(['data-id' => '123']);
205 |      * ```
206 |      */
207 |     public function attributes(array $attributes): self
208 |     {
209 |         $new = clone $this;
210 |         $new->attributes = $attributes;
211 | 
212 |         return $new;
213 |     }
214 | 
215 |     /**
216 |      * Sets the background color of the bar.
217 |      *
218 |      * @param BackgroundColor $color The background color class to apply to the bar.
219 |      *
220 |      * @return self A new instance with the specified background color applied.
221 |      *
222 |      * @link https://getbootstrap.com/docs/5.3/components/progress/#backgrounds
223 |      *
224 |      * Example usage:
225 |      * ```php
226 |      * $progress->backgroundColor(BackgroundColor::SUCCESS);
227 |      * ```
228 |      */
229 |     public function backgroundColor(BackgroundColor $color): self
230 |     {
231 |         return $this->addBarClass($color);
232 |     }
233 | 
234 |     /**
235 |      * Sets the HTML attributes for the bar.
236 |      *
237 |      * @param array $attributes Attribute values indexed by attribute names.
238 |      *
239 |      * @return self A new instance with the specified attributes for the bar.
240 |      *
241 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
242 |      *
243 |      * Example usage:
244 |      * ```php
245 |      * $progress->barAttributes(['data-id' => '123']);
246 |      * ```
247 |      */
248 |     public function barAttributes(array $attributes): self
249 |     {
250 |         $new = clone $this;
251 |         $new->barAttributes = $attributes;
252 | 
253 |         return $new;
254 |     }
255 | 
256 |     /**
257 |      * Replaces all existing CSS classes with the specified one(s).
258 |      *
259 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
260 |      *
261 |      * @return self A new instance with the specified CSS classes set.
262 |      *
263 |      * Example usage:
264 |      * ```php
265 |      * $progress->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
266 |      * ```
267 |      */
268 |     public function class(BackedEnum|string|null ...$class): self
269 |     {
270 |         $new = clone $this;
271 |         $new->cssClasses = $class;
272 | 
273 |         return $new;
274 |     }
275 | 
276 |     /**
277 |      * Sets the content.
278 |      *
279 |      * @param string $content The content to be displayed in the bar.
280 |      *
281 |      * @return self A new instance with the specified content.
282 |      *
283 |      * Example usage:
284 |      * ```php
285 |      * $progress->content('Loading...');
286 |      * ```
287 |      */
288 |     public function content(string $content): self
289 |     {
290 |         $new = clone $this;
291 |         $new->content = $content;
292 | 
293 |         return $new;
294 |     }
295 | 
296 |     /**
297 |      * Sets the ID.
298 |      *
299 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
300 |      *
301 |      * @return self A new instance with the specified ID.
302 |      *
303 |      * Example usage:
304 |      * ```php
305 |      * $progress->id('my-id');
306 |      * ```
307 |      */
308 |     public function id(bool|string $id): self
309 |     {
310 |         $new = clone $this;
311 |         $new->id = $id;
312 | 
313 |         return $new;
314 |     }
315 | 
316 |     /**
317 |      * Sets the maximum value.
318 |      *
319 |      * @param float|int $max The maximum value. This value is used to calculate the progress percentage.
320 |      *
321 |      * @return self A new instance with the specified maximum value.
322 |      *
323 |      * Example usage:
324 |      * ```php
325 |      * $progress->max(200);
326 |      * ```
327 |      */
328 |     public function max(int|float $max): self
329 |     {
330 |         $new = clone $this;
331 |         $new->max = $max;
332 | 
333 |         return $new;
334 |     }
335 | 
336 |     /**
337 |      * Sets the minimum value.
338 |      *
339 |      * @param float|int $min The minimum value. This value is used to calculate the progress percentage.
340 |      *
341 |      * @return self A new instance with the specified minimum value.
342 |      *
343 |      * Example usage:
344 |      * ```php
345 |      * $progress->min(50);
346 |      * ```
347 |      */
348 |     public function min(int|float $min): self
349 |     {
350 |         $new = clone $this;
351 |         $new->min = $min;
352 | 
353 |         return $new;
354 |     }
355 | 
356 |     /**
357 |      * Sets the percentage value for the bar.
358 |      *
359 |      * @param float|int $percent The percentage value. Must be greater than or equal to 0.
360 |      *
361 |      * @throws LogicException When percentage value is less than 0.
362 |      *
363 |      * @return self A new instance with the specified percentage value.
364 |      *
365 |      * Example usage:
366 |      * ```php
367 |      * $progress->percent(60);
368 |      * ```
369 |      */
370 |     public function percent(int|float $percent): self
371 |     {
372 |         if ($percent < 0) {
373 |             throw new LogicException(
374 |                 sprintf('"$percent" must be positive. %d given', $percent)
375 |             );
376 |         }
377 | 
378 |         $new = clone $this;
379 |         $new->percent = $percent;
380 | 
381 |         return $new;
382 |     }
383 | 
384 |     /**
385 |      * Sets the sizing variant.
386 |      *
387 |      * @param Sizing $size The sizing variant to apply. This affects the width class of the bar.
388 |      *
389 |      * @return self A new instance with the specified sizing variant.
390 |      *
391 |      * Example usage:
392 |      * ```php
393 |      * $progress->sizing(Sizing::WIDTH_75);
394 |      * ```
395 |      */
396 |     public function sizing(Sizing $size): self
397 |     {
398 |         $new = clone $this;
399 |         $new->sizing = true;
400 | 
401 |         return $new->addBarClass($size);
402 |     }
403 | 
404 |     /**
405 |      * Sets the bar to be stacked.
406 |      *
407 |      * @return self A new instance with the bar stacked.
408 |      *
409 |      * Example usage:
410 |      * ```php
411 |      * $progress->stacked();
412 |      * ```
413 |      */
414 |     public function stacked(): self
415 |     {
416 |         $new = clone $this;
417 |         $new->stacked = true;
418 | 
419 |         return $new;
420 |     }
421 | 
422 |     /**
423 |      * Sets the variant.
424 |      *
425 |      * @param ProgressVariant $variant The variant to apply to the progress bar.
426 |      *
427 |      * @return self A new instance with the specified variant.
428 |      *
429 |      * Example usage:
430 |      * ```php
431 |      * $progress->variant(ProgressVariant::ANIMATED_STRIPED);
432 |      * ```
433 |      */
434 |     public function variant(ProgressVariant $variant): self
435 |     {
436 |         return $this->addBarClass($variant);
437 |     }
438 | 
439 |     /**
440 |      * Run the widget.
441 |      *
442 |      * @return string The HTML representation of the element.
443 |      */
444 |     public function render(): string
445 |     {
446 |         $attributes = $this->attributes;
447 |         $classes = $attributes['class'] ?? null;
448 | 
449 |         unset($attributes['class']);
450 | 
451 |         if ($this->stacked) {
452 |             $attributes['style'] = 'width: ' . $this->percent . '%';
453 |         }
454 | 
455 |         return Div::tag()
456 |             ->attributes($attributes)
457 |             ->addClass(
458 |                 self::NAME,
459 |                 ...$this->cssClasses,
460 |             )
461 |             ->addClass($classes)
462 |             ->attribute('role', 'progressbar')
463 |             ->attribute('aria-valuenow', $this->percent)
464 |             ->attribute('aria-valuemin', $this->min)
465 |             ->attribute('aria-valuemax', $this->max)
466 |             ->content(
467 |                 "\n",
468 |                 $this->renderBar(),
469 |                 "\n",
470 |             )
471 |             ->id($this->getId())
472 |             ->encode(false)
473 |             ->render();
474 |     }
475 | 
476 |     /**
477 |      * Generates the ID.
478 |      *
479 |      * @return string|null The generated ID.
480 |      *
481 |      * @psalm-return non-empty-string|null The generated ID.
482 |      */
483 |     private function getId(): string|null
484 |     {
485 |         return match ($this->id) {
486 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
487 |             '', false => null,
488 |             default => $this->id,
489 |         };
490 |     }
491 | 
492 |     /**
493 |      * Renders the bar.
494 |      *
495 |      * @return string The HTML representation of the element.
496 |      */
497 |     private function renderBar(): string
498 |     {
499 |         $barAttributes = $this->barAttributes;
500 |         $barClasses = $barAttributes['class'] ?? null;
501 | 
502 |         unset($barAttributes['class']);
503 | 
504 |         if ($this->stacked === false && $this->sizing === false) {
505 |             $barAttributes['style'] = 'width: ' . $this->percent . '%';
506 |         }
507 | 
508 |         $renderBar = Div::tag()
509 |             ->attributes($barAttributes)
510 |             ->addClass(self::PROGRESS_BAR, ...$this->barClasses)
511 |             ->addClass($barClasses)
512 |             ->encode(false);
513 | 
514 |         if ($this->content !== '') {
515 |             $renderBar = $renderBar->content("\n", $this->content, "\n");
516 |         }
517 | 
518 |         return $renderBar->render();
519 |     }
520 | }
521 | 


--------------------------------------------------------------------------------
/src/Breadcrumbs.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use InvalidArgumentException;
  9 | use RuntimeException;
 10 | use Yiisoft\Html\Html;
 11 | use Yiisoft\Html\Tag\A;
 12 | use Yiisoft\Html\Tag\Li;
 13 | use Yiisoft\Html\Tag\Nav;
 14 | use Yiisoft\Widget\Widget;
 15 | 
 16 | use function implode;
 17 | use function sprintf;
 18 | 
 19 | /**
 20 |  * Button renders a bootstrap button.
 21 |  *
 22 |  * For example,
 23 |  *
 24 |  * ```php
 25 |  * <?= Breadcrumbs::widget()
 26 |  *         ->links(
 27 |  *             BreadcrumbLink::to('Home', '#'),
 28 |  *             BreadcrumbLink::to('Library', '#'),
 29 |  *             BreadcrumbLink::to('Data', active: true),
 30 |  *         )
 31 |  *         ->listId(false)
 32 |  * ?>
 33 |  * ```
 34 |  *
 35 |  * @see https://getbootstrap.com/docs/5.3/components/breadcrumb/
 36 |  */
 37 | final class Breadcrumbs extends Widget
 38 | {
 39 |     private const LIST_NAME = 'breadcrumb';
 40 | 
 41 |     private const ITEM_NAME = 'breadcrumb-item';
 42 | 
 43 |     private array $attributes = [];
 44 | 
 45 |     private array $cssClasses = [];
 46 | 
 47 |     private string $itemActiveClass = 'active';
 48 | 
 49 |     private array $itemAttributes = [];
 50 | 
 51 |     private array $linkAttributes = [];
 52 | 
 53 |     private array $links = [];
 54 | 
 55 |     private array $listAttributes = [];
 56 | 
 57 |     private bool|string $listId = true;
 58 | 
 59 |     private string $listTagName = 'ol';
 60 | 
 61 |     /**
 62 |      * Adds a sets of attributes.
 63 |      *
 64 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 65 |      *
 66 |      * @return self A new instance with the specified attributes added.
 67 |      *
 68 |      * Example usage:
 69 |      * ```php
 70 |      * $breadcrumb->addAttributes(['data-id' => '123']);
 71 |      * ```
 72 |      */
 73 |     public function addAttributes(array $attributes): self
 74 |     {
 75 |         $new = clone $this;
 76 |         $new->attributes = [...$new->attributes, ...$attributes];
 77 | 
 78 |         return $new;
 79 |     }
 80 | 
 81 |     /**
 82 |      * Adds one or more CSS classes to the existing classes.
 83 |      *
 84 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
 85 |      * automatically.
 86 |      *
 87 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
 88 |      *
 89 |      * @return self A new instance with the specified CSS classes added to existing ones.
 90 |      *
 91 |      * @link https://html.spec.whatwg.org/#classes
 92 |      *
 93 |      * Example usage:
 94 |      * ```php
 95 |      * $breadcrumb->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
 96 |      * ```
 97 |      */
 98 |     public function addClass(BackedEnum|string|null ...$class): self
 99 |     {
100 |         $new = clone $this;
101 |         $new->cssClasses = [...$this->cssClasses, ...$class];
102 | 
103 |         return $new;
104 |     }
105 | 
106 |     /**
107 |      * Adds a CSS style.
108 |      *
109 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
110 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
111 |      * If it is a string, it will be added as is, for example, `color: red`.
112 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
113 |      * appended to the existing one.
114 |      *
115 |      * @return self A new instance with the specified CSS style value added.
116 |      *
117 |      * Example usage:
118 |      * ```php
119 |      * $breadcrumb->addCssStyle('color: red');
120 |      *
121 |      * // or
122 |      * $breadcrumb->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
123 |      * ```
124 |      */
125 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
126 |     {
127 |         $new = clone $this;
128 |         Html::addCssStyle($new->attributes, $style, $overwrite);
129 | 
130 |         return $new;
131 |     }
132 | 
133 |     /**
134 |      * Sets the ARIA label.
135 |      *
136 |      * @param string $label The ARIA label.
137 |      *
138 |      * @return self A new instance with the specified ARIA label.
139 |      *
140 |      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-label
141 |      *
142 |      * Example usage:
143 |      * ```php
144 |      * $breadcrumb->ariaLabel('breadcrumb');
145 |      * ```
146 |      */
147 |     public function ariaLabel(string $label): self
148 |     {
149 |         return $this->attribute('aria-label', $label);
150 |     }
151 | 
152 |     /**
153 |      * Adds a sets attribute value.
154 |      *
155 |      * @param string $name The attribute name.
156 |      * @param mixed $value The attribute value.
157 |      *
158 |      * @return self A new instance with the specified attribute added.
159 |      *
160 |      * Example usage:
161 |      * ```php
162 |      * $breadcrumb->attribute('data-id', '123');
163 |      * ```
164 |      */
165 |     public function attribute(string $name, mixed $value): self
166 |     {
167 |         $new = clone $this;
168 |         $new->attributes[$name] = $value;
169 | 
170 |         return $new;
171 |     }
172 | 
173 |     /**
174 |      * Sets the HTML attributes.
175 |      *
176 |      * @param array $attributes Attribute values indexed by attribute names.
177 |      *
178 |      * @return self A new instance with the specified attributes.
179 |      *
180 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
181 |      *
182 |      * Example usage:
183 |      * ```php
184 |      * $breadcrumb->attributes(['data-id' => '123']);
185 |      * ```
186 |      */
187 |     public function attributes(array $attributes): self
188 |     {
189 |         $new = clone $this;
190 |         $new->attributes = $attributes;
191 | 
192 |         return $new;
193 |     }
194 | 
195 |     /**
196 |      * Replaces all existing CSS classes with the specified one(s).
197 |      *
198 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
199 |      * automatically.
200 |      *
201 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
202 |      *
203 |      * @return self A new instance with the specified CSS classes set.
204 |      *
205 |      * Example usage:
206 |      * ```php
207 |      * $breadcrumb->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
208 |      * ```
209 |      */
210 |     public function class(BackedEnum|string|null ...$class): self
211 |     {
212 |         $new = clone $this;
213 |         $new->cssClasses = $class;
214 | 
215 |         return $new;
216 |     }
217 | 
218 |     /**
219 |      * Sets the divider.
220 |      *
221 |      * @param string $content The divider.
222 |      *
223 |      * @throws InvalidArgumentException If the divider is an empty string.
224 |      *
225 |      * @return self A new instance with the specified divider.
226 |      *
227 |      * Example usage:
228 |      * ```php
229 |      * $breadcrumb->divider('/');
230 |      * ```
231 |      */
232 |     public function divider(string $content): self
233 |     {
234 |         if ($content === '') {
235 |             throw new InvalidArgumentException('The "divider" cannot be empty.');
236 |         }
237 | 
238 |         return $this->attribute('style', ['--bs-breadcrumb-divider' => sprintf("'%s'", $content)]);
239 |     }
240 | 
241 |     /**
242 |      * Sets the active class for the items.
243 |      *
244 |      * @param string $class The active class for the items.
245 |      *
246 |      * @return self A new instance with the specified active class for the items.
247 |      *
248 |      * Example usage:
249 |      * ```php
250 |      * $breadcrumb->itemActiveClass('active');
251 |      * ```
252 |      */
253 |     public function itemActiveClass(string $class): self
254 |     {
255 |         $new = clone $this;
256 |         $new->itemActiveClass = $class;
257 | 
258 |         return $new;
259 |     }
260 | 
261 |     /**
262 |      * Sets the HTML attributes for the items.
263 |      *
264 |      * @param array $attributes Attribute values indexed by attribute names.
265 |      *
266 |      * @return self A new instance with the specified attributes for the items.
267 |      *
268 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
269 |      *
270 |      * Example usage:
271 |      * ```php
272 |      * $breadcrumb->itemAttributes(['class' => 'my-class']);
273 |      * ```
274 |      */
275 |     public function itemAttributes(array $attributes): self
276 |     {
277 |         $new = clone $this;
278 |         $new->itemAttributes = $attributes;
279 | 
280 |         return $new;
281 |     }
282 | 
283 |     /**
284 |      * Sets the HTML attributes for the link of the items.
285 |      *
286 |      * @param array $attributes Attribute values indexed by attribute names.
287 |      *
288 |      * @return self A new instance with the specified attributes for the link of the items.
289 |      *
290 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
291 |      *
292 |      * Example usage:
293 |      * ```php
294 |      * $breadcrumb->linkAttributes(['class' => 'my-class']);
295 |      * ```
296 |      */
297 |     public function linkAttributes(array $attributes): self
298 |     {
299 |         $new = clone $this;
300 |         $new->linkAttributes = $attributes;
301 | 
302 |         return $new;
303 |     }
304 | 
305 |     /**
306 |      * List of links. If this property is empty, the widget will not render anything.
307 |      *
308 |      * @param BreadcrumbLink ...$links The links.
309 |      *
310 |      * @return self A new instance with the specified links.
311 |      *
312 |      * @psalm-param BreadcrumbLink[] $links The links.
313 |      *
314 |      * Example usage:
315 |      * ```php
316 |      * $breadcrumb->links(
317 |      *     BreadcrumbLink::to('Home', '#'),
318 |      *     BreadcrumbLink::to('Library', '#'),
319 |      *     BreadcrumbLink::to('Data', active: true),
320 |      * );
321 |      * ```
322 |      */
323 |     public function links(BreadcrumbLink ...$links): self
324 |     {
325 |         $new = clone $this;
326 |         $new->links = $links;
327 | 
328 |         return $new;
329 |     }
330 | 
331 |     /**
332 |      * Sets the HTML attributes for the list of items.
333 |      *
334 |      * @param array $attributes Attribute values indexed by attribute names.
335 |      *
336 |      * @return self A new instance with the specified attributes for the list of items.
337 |      *
338 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
339 |      *
340 |      * Example usage:
341 |      * ```php
342 |      * $breadcrumb->listAttributes(['class' => 'my-class']);
343 |      * ```
344 |      */
345 |     public function listAttributes(array $attributes): self
346 |     {
347 |         $new = clone $this;
348 |         $new->listAttributes = $attributes;
349 | 
350 |         return $new;
351 |     }
352 | 
353 |     /**
354 |      * Sets the ID of the item list.
355 |      *
356 |      * @param bool|string $id The ID. If `true`, an ID will be generated automatically.
357 |      *
358 |      * @return self A new instance with the specified ID for the list of items.
359 |      *
360 |      * Example usage:
361 |      * ```php
362 |      * $breadcrumb->listId('my-id');
363 |      * ```
364 |      */
365 |     public function listId(bool|string $id): self
366 |     {
367 |         $new = clone $this;
368 |         $new->listId = $id;
369 | 
370 |         return $new;
371 |     }
372 | 
373 |     /**
374 |      * Sets the HTML tag to be used for the list of items.
375 |      *
376 |      * @param string $tag The HTML tag name for the list of items.
377 |      *
378 |      * @throws InvalidArgumentException If the tag name is empty.
379 |      *
380 |      * @return self A new instance class with the specified list tag name.
381 |      *
382 |      * Example usage:
383 |      * ```php
384 |      * $breadcrumb->listTagName('ul');
385 |      * ```
386 |      */
387 |     public function listTagName(string $tag): self
388 |     {
389 |         $new = clone $this;
390 |         $new->listTagName = $tag;
391 | 
392 |         return $new;
393 |     }
394 | 
395 |     /**
396 |      * Run the widget.
397 |      *
398 |      * @return string The HTML representation of the element.
399 |      */
400 |     public function render(): string
401 |     {
402 |         $attributes = $this->attributes;
403 |         $attributes['aria-label'] ??= 'breadcrumb';
404 | 
405 |         if ($this->links === []) {
406 |             return '';
407 |         }
408 | 
409 | 
410 |         return Nav::tag()
411 |             ->addAttributes($attributes)
412 |             ->addClass(...$this->cssClasses)
413 |             ->content("\n", $this->renderList(), "\n")
414 |             ->encode(false)
415 |             ->render();
416 |     }
417 | 
418 |     /**
419 |      * Generates the ID.
420 |      *
421 |      * @return string|null The generated ID.
422 |      *
423 |      * @psalm-return non-empty-string|null The generated ID.
424 |      */
425 |     private function getId(): string|null
426 |     {
427 |         return match ($this->listId) {
428 |             true => $this->listAttributes['id'] ?? Html::generateId(self::LIST_NAME . '-'),
429 |             '', false => null,
430 |             default => $this->listId,
431 |         };
432 |     }
433 | 
434 |     /**
435 |      * Renders the list of items.
436 |      *
437 |      * @return string The HTML representation of the element.
438 |      */
439 |     private function renderList(): string
440 |     {
441 |         $listAttributes = $this->listAttributes;
442 |         $classes = $listAttributes['class'] ?? null;
443 | 
444 |         unset($listAttributes['class'], $listAttributes['id']);
445 | 
446 |         $items = [];
447 |         $active = 0;
448 | 
449 |         foreach ($this->links as $link) {
450 |             $active += (int) $link->isActive();
451 |             $items[] = $this->renderItem($link);
452 | 
453 |             if ($active > 1) {
454 |                 throw new RuntimeException('Only one "link" can be active.');
455 |             }
456 |         }
457 | 
458 |         $items = implode("\n", $items);
459 | 
460 |         if ($this->listTagName === '') {
461 |             throw new InvalidArgumentException('List tag cannot be empty.');
462 |         }
463 | 
464 |         return Html::tag($this->listTagName)
465 |             ->addAttributes($listAttributes)
466 |             ->addClass(
467 |                 self::LIST_NAME,
468 |                 $classes,
469 |             )
470 |             ->content("\n", $items, "\n")
471 |             ->id($this->getId())
472 |             ->encode(false)
473 |             ->render();
474 |     }
475 | 
476 |     /**
477 |      * Renders a single breadcrumb item.
478 |      *
479 |      * @param BreadcrumbLink $breadcrumbLink The breadcrumb item to render.
480 |      *
481 |      * @return string The HTML representation of the element.
482 |      */
483 |     private function renderItem(BreadcrumbLink $breadcrumbLink): string
484 |     {
485 |         $itemsAttributes = $this->itemAttributes;
486 |         $classes = $itemsAttributes['class'] ?? null;
487 | 
488 |         unset($itemsAttributes['class']);
489 | 
490 |         $linkTag = $this->renderLink($breadcrumbLink);
491 | 
492 |         if ($breadcrumbLink->isActive()) {
493 |             $itemsAttributes['aria-current'] = 'page';
494 |         }
495 | 
496 |         return Li::tag()
497 |             ->addAttributes($itemsAttributes)
498 |             ->addClass(
499 |                 self::ITEM_NAME,
500 |                 $classes,
501 |                 $breadcrumbLink->isActive() ? $this->itemActiveClass : null,
502 |             )
503 |             ->content($linkTag)
504 |             ->encode(false)
505 |             ->render();
506 |     }
507 | 
508 |     /**
509 |      * Renders a single breadcrumb link.
510 |      *
511 |      * @param BreadcrumbLink $breadcrumbLink The breadcrumb link to render.
512 |      *
513 |      * @return string The HTML representation of the element.
514 |      */
515 |     private function renderLink(BreadcrumbLink $breadcrumbLink): string
516 |     {
517 |         $label = $breadcrumbLink->getLabel();
518 |         $url = $breadcrumbLink->getUrl();
519 | 
520 |         return match ($url) {
521 |             null => $label,
522 |             default => A::tag()
523 |                 ->attributes($this->linkAttributes)
524 |                 ->addAttributes($breadcrumbLink->getAttributes())
525 |                 ->content($label)
526 |                 ->url($url)
527 |                 ->encode(false)
528 |                 ->render(),
529 |         };
530 |     }
531 | }
532 | 


--------------------------------------------------------------------------------
/src/Button.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use Stringable;
  9 | use Yiisoft\Bootstrap5\Utility\TogglerType;
 10 | use Yiisoft\Definitions\Exception\CircularReferenceException;
 11 | use Yiisoft\Definitions\Exception\InvalidConfigException;
 12 | use Yiisoft\Definitions\Exception\NotInstantiableException;
 13 | use Yiisoft\Factory\NotFoundException;
 14 | use Yiisoft\Html\Html;
 15 | use Yiisoft\Html\Tag\A;
 16 | use Yiisoft\Html\Tag\Button as ButtonTag;
 17 | use Yiisoft\Html\Tag\Input;
 18 | use Yiisoft\Widget\Widget;
 19 | 
 20 | /**
 21 |  * Button renders a bootstrap button.
 22 |  *
 23 |  * For example,
 24 |  *
 25 |  * ```php
 26 |  * <?= Button::widget()
 27 |  *         ->label('Button')
 28 |  *         ->largeSize()
 29 |  *         ->variant(ButtonVariant::PRIMARY)
 30 |  * ?>
 31 |  * ```
 32 |  *
 33 |  * @link https://getbootstrap.com/docs/5.3/components/buttons/
 34 |  */
 35 | final class Button extends Widget
 36 | {
 37 |     private const NAME = 'btn';
 38 | 
 39 |     private array $attributes = [];
 40 | 
 41 |     private ButtonVariant|null $buttonVariant = ButtonVariant::SECONDARY;
 42 | 
 43 |     private array $cssClasses = [];
 44 | 
 45 |     private bool $disabled = false;
 46 | 
 47 |     private bool|string $id = true;
 48 | 
 49 |     private string|Stringable $label = '';
 50 | 
 51 |     private A|ButtonTag|Input|null $tag = null;
 52 | 
 53 |     /**
 54 |      * Whether the button should be a link.
 55 |      *
 56 |      * @param string|Stringable $label The content.
 57 |      * @param string|null $url The URL of the link.
 58 |      * @param array $constructorArguments The constructor arguments.
 59 |      * @param array $config The configuration.
 60 |      * @param string|null $theme The theme.
 61 |      *
 62 |      * @throws CircularReferenceException
 63 |      * @throws InvalidConfigException
 64 |      * @throws NotFoundException
 65 |      * @throws NotInstantiableException
 66 |      *
 67 |      * @return self A new instance with the button as a link.
 68 |      *
 69 |      * Example usage:
 70 |      * ```php
 71 |      * Button::link('Button', '/path/to/page');
 72 |      * ```
 73 |  */
 74 |     public static function link(
 75 |         string|Stringable $label = '',
 76 |         string|null $url = null,
 77 |         array $constructorArguments = [],
 78 |         array $config = [],
 79 |         string|null $theme = null
 80 |     ): self {
 81 |         return self::widget($constructorArguments, $config, $theme)->label($label)->type(ButtonType::LINK)->url($url);
 82 |     }
 83 | 
 84 |     /**
 85 |      * Get an instance of a reset button input.
 86 |      *
 87 |      * @param string|Stringable $value The content. By default, it's "Reset".
 88 |      * @param array $constructorArguments The constructor arguments.
 89 |      * @param array $config The configuration.
 90 |      * @param string|null $theme The theme.
 91 |      *
 92 |      * @throws CircularReferenceException
 93 |      * @throws InvalidConfigException
 94 |      * @throws NotFoundException
 95 |      * @throws NotInstantiableException
 96 |      *
 97 |      * @return self A new instance with the input of "reset" type.
 98 |      *
 99 |      * Example usage:
100 |      * ```php
101 |      * Button::resetInput('Reset');
102 |      * ```
103 |      */
104 |     public static function resetInput(
105 |         string|Stringable $value = 'Reset',
106 |         array $constructorArguments = [],
107 |         array $config = [],
108 |         string|null $theme = null
109 |     ): self {
110 |         return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::RESET_INPUT);
111 |     }
112 | 
113 |     /**
114 |      * Get an instance of a "submit" button input.
115 |      *
116 |      * @param string|Stringable $value The content. By default, it's "Submit".
117 |      * @param array $constructorArguments The constructor arguments.
118 |      * @param array $config The configuration.
119 |      * @param string|null $theme The theme.
120 |      *
121 |      * @throws CircularReferenceException
122 |      * @throws InvalidConfigException
123 |      * @throws NotFoundException
124 |      * @throws NotInstantiableException
125 |      *
126 |      * @return self A new instance of an input with "submit" type.
127 |      *
128 |      * Example usage:
129 |      * ```php
130 |      * Button::submitInput('Submit');
131 |      * ```
132 |      */
133 |     public static function submitInput(
134 |         string|Stringable $value = 'Submit',
135 |         array $constructorArguments = [],
136 |         array $config = [],
137 |         string|null $theme = null
138 |     ): self {
139 |         return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::SUBMIT_INPUT);
140 |     }
141 | 
142 |     /**
143 |      * Whether the button should be a reset button.
144 |      *
145 |      * @param string|Stringable $value The content. For default, it is 'Reset'.
146 |      * @param array $constructorArguments The constructor arguments.
147 |      * @param array $config The configuration.
148 |      * @param string|null $theme The theme.
149 |      *
150 |      * @throws CircularReferenceException
151 |      * @throws InvalidConfigException
152 |      * @throws NotFoundException
153 |      * @throws NotInstantiableException
154 |      *
155 |      * @return self A new instance with the button as a reset button.
156 |      *
157 |      * Example usage:
158 |      * ```php
159 |      * Button::reset('Reset');
160 |      * ```
161 |      */
162 |     public static function reset(
163 |         string|Stringable $value = 'Reset',
164 |         array $constructorArguments = [],
165 |         array $config = [],
166 |         string|null $theme = null
167 |     ): self {
168 |         return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::RESET);
169 |     }
170 | 
171 |     /**
172 |      * Whether the button should be a "submit" button.
173 |      *
174 |      * @param string|Stringable $value The content. For default, it is "Submit".
175 |      * @param array $constructorArguments The constructor arguments.
176 |      * @param array $config The configuration.
177 |      * @param string|null $theme The theme.
178 |      *
179 |      * @throws CircularReferenceException
180 |      * @throws InvalidConfigException
181 |      * @throws NotFoundException
182 |      * @throws NotInstantiableException
183 |      *
184 |      * @return self A new instance with the button as a "submit" button.
185 |      *
186 |      * Example usage:
187 |      * ```php
188 |      * Button::submit('Submit');
189 |      * ```
190 |      */
191 |     public static function submit(
192 |         string|Stringable $value = 'Submit',
193 |         array $constructorArguments = [],
194 |         array $config = [],
195 |         string|null $theme = null
196 |     ): self {
197 |         return self::widget($constructorArguments, $config, $theme)->label($value)->type(ButtonType::SUBMIT);
198 |     }
199 | 
200 |     /**
201 |      * Sets the active state.
202 |      *
203 |      * @param bool $enabled Whether the button should be active.
204 |      *
205 |      * @return self A new instance with the button active.
206 |      *
207 |      * Example usage:
208 |      * ```php
209 |      * $button->active();
210 |      * ```
211 |      */
212 |     public function active(bool $enabled = true): self
213 |     {
214 |         return $this
215 |             ->toggle($enabled ? TogglerType::BUTTON : null)
216 |             ->addClass($enabled ? 'active' : null)
217 |             ->attribute('aria-pressed', $enabled ? 'true' : null);
218 |     }
219 | 
220 |     /**
221 |      * Adds a sets of attributes.
222 |      *
223 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
224 |      *
225 |      * @return self A new instance with the specified attributes added.
226 |      *
227 |      * Example usage:
228 |      * ```php
229 |      * $button->addAttributes(['data-id' => '123']);
230 |      * ```
231 |      */
232 |     public function addAttributes(array $attributes): self
233 |     {
234 |         $new = clone $this;
235 |         $new->attributes = [...$this->attributes, ...$attributes];
236 | 
237 |         return $new;
238 |     }
239 | 
240 |     /**
241 |      * Adds one or more CSS classes to the existing classes.
242 |      *
243 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
244 |      * automatically.
245 |      *
246 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
247 |      *
248 |      * @return self A new instance with the specified CSS classes added to existing ones.
249 |      *
250 |      * @link https://html.spec.whatwg.org/#classes
251 |      *
252 |      * Example usage:
253 |      * ```php
254 |      * $button->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
255 |      * ```
256 |      */
257 |     public function addClass(BackedEnum|string|null ...$class): self
258 |     {
259 |         $new = clone $this;
260 |         $new->cssClasses = [...$this->cssClasses, ...$class];
261 | 
262 |         return $new;
263 |     }
264 | 
265 |     /**
266 |      * Adds a CSS style.
267 |      *
268 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
269 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
270 |      * If it is a string, it will be added as is, for example, `color: red`.
271 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
272 |      * appended to the existing one.
273 |      *
274 |      * @return self A new instance with the specified CSS style value added.
275 |      *
276 |      * Example usage:
277 |      * ```php
278 |      * $button->addCssStyle('color: red');
279 |      *
280 |      * // or
281 |      * $button->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
282 |      * ```
283 |      */
284 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
285 |     {
286 |         $new = clone $this;
287 |         Html::addCssStyle($new->attributes, $style, $overwrite);
288 | 
289 |         return $new;
290 |     }
291 | 
292 |     /**
293 |      * Sets the 'aria-expanded' attribute, indicating whether the element is currently expanded or collapsed.
294 |      *
295 |      * @param bool $enabled The value to set for the 'aria-expanded' attribute.
296 |      *
297 |      * @return self A new instance with the specified 'aria-expanded' value.
298 |      *
299 |      * @link https://www.w3.org/TR/wai-aria-1.1/#aria-expanded
300 |      *
301 |      * Example usage:
302 |      * ```php
303 |      * $button->ariaExpanded();
304 |      * ```
305 |      */
306 |     public function ariaExpanded(bool $enabled = true): self
307 |     {
308 |         return $this->attribute('aria-expanded', $enabled ? 'true' : 'false');
309 |     }
310 | 
311 |     /**
312 |      * Adds a sets attribute value.
313 |      *
314 |      * @param string $name The attribute name.
315 |      * @param mixed $value The attribute value.
316 |      *
317 |      * @return self A new instance with the specified attribute added.
318 |      *
319 |      * Example usage:
320 |      * ```php
321 |      * $button->attribute('data-id', '123');
322 |      * ```
323 |      */
324 |     public function attribute(string $name, mixed $value): self
325 |     {
326 |         $new = clone $this;
327 |         $new->attributes[$name] = $value;
328 | 
329 |         return $new;
330 |     }
331 | 
332 |     /**
333 |      * Sets the HTML attributes.
334 |      *
335 |      * @param array $attributes Attribute values indexed by attribute names.
336 |      *
337 |      * @return self A new instance with the specified attributes.
338 |      *
339 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
340 |      *
341 |      * Example usage:
342 |      * ```php
343 |      * $button->attributes(['data-id' => '123']);
344 |      * ```
345 |      */
346 |     public function attributes(array $attributes): self
347 |     {
348 |         $new = clone $this;
349 |         $new->attributes = $attributes;
350 | 
351 |         return $new;
352 |     }
353 | 
354 |     /**
355 |      * Replaces all existing CSS classes with the specified one(s).
356 |      *
357 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
358 |      * automatically.
359 |      *
360 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
361 |      *
362 |      * @return self A new instance with the specified CSS classes set.
363 |      *
364 |      * Example usage:
365 |      * ```php
366 |      * $button->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
367 |      * ```
368 |      */
369 |     public function class(BackedEnum|string|null ...$class): self
370 |     {
371 |         $new = clone $this;
372 |         $new->cssClasses = $class;
373 | 
374 |         return $new;
375 |     }
376 | 
377 |     /**
378 |      * Add `text-nowrap` CSS class to prevent text from wrapping.
379 |      *
380 |      * @return self A new instance with the text wrapping disabled.
381 |      *
382 |      * Example usage:
383 |      * ```php
384 |      * $button->disableTextWrapping();
385 |      * ```
386 |      */
387 |     public function disableTextWrapping(): self
388 |     {
389 |         return $this->addClass('text-nowrap');
390 |     }
391 | 
392 |     /**
393 |      * Sets the disable state.
394 |      *
395 |      * @param bool $enabled Whether the button should be disabled.
396 |      *
397 |      * @return self A new instance with the button disabled.
398 |      *
399 |      * Example usage:
400 |      * ```php
401 |      * $button->disabled();
402 |      * ```
403 |      */
404 |     public function disabled(bool $enabled = true): self
405 |     {
406 |         $new = clone $this;
407 |         $new->disabled = $enabled;
408 | 
409 |         return $new;
410 |     }
411 | 
412 |     /**
413 |      * Sets the ID.
414 |      *
415 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
416 |      *
417 |      * @return self A new instance with the specified ID.
418 |      *
419 |      * Example usage:
420 |      * ```php
421 |      * $button->id('my-id');
422 |      * ```
423 |      */
424 |     public function id(bool|string $id): self
425 |     {
426 |         $new = clone $this;
427 |         $new->id = $id;
428 | 
429 |         return $new;
430 |     }
431 | 
432 |     /**
433 |      * The label.
434 |      *
435 |      * @param string|Stringable $label The label to display on the button.
436 |      * @param bool $encode Whether the label value should be HTML-encoded. Use this when rendering user-generated
437 |      * content to prevent XSS attacks.
438 |      *
439 |      * @return self A new instance with the specified label value.
440 |      *
441 |      * Example usage:
442 |      * ```php
443 |      * $button->label('Button');
444 |      * ```
445 |      */
446 |     public function label(string|Stringable $label, bool $encode = true): self
447 |     {
448 |         if ($encode) {
449 |             $label = Html::encode($label);
450 |         }
451 | 
452 |         $new = clone $this;
453 |         $new->label = $label;
454 | 
455 |         return $new;
456 |     }
457 | 
458 |     /**
459 |      * Sets the size.
460 |      *
461 |      * @param ButtonSize|null $size The size. If `null`, the size will not be set.
462 |      *
463 |      * @return self A new instance with the specified size.
464 |      *
465 |      * Example usage:
466 |      * ```php
467 |      * $button->size(ButtonSize::LARGE);
468 |      * ```
469 |      */
470 |     public function size(ButtonSize|null $size): self
471 |     {
472 |         return $this->addClass($size?->value);
473 |     }
474 | 
475 |     /**
476 |      * Sets the toggle behavior by the `data-bs-toggle` attribute, enabling interactive functionality such as `button`,
477 |      * `dropdown`, `modal`, and `tooltip`.
478 |      *
479 |      * @param TogglerType|null $type The toggle type to be set. If `null`, the toggle behavior will not be set.
480 |      *
481 |      * @return self A new instance with the specified toggle behavior.
482 |      *
483 |      * Example usage:
484 |      * ```php
485 |      * $button->toggle(TogglerType::BUTTON);
486 |      * ```
487 |      */
488 |     public function toggle(TogglerType|null $type = TogglerType::BUTTON): self
489 |     {
490 |         return $this->attribute('data-bs-toggle', $type?->value);
491 |     }
492 | 
493 |     /**
494 |      * Sets the type.
495 |      *
496 |      * @param ButtonType $type The type.
497 |      *
498 |      * @return self A new instance with the specified type.
499 |      *
500 |      * Example usage:
501 |      * ```php
502 |      * $button->type(ButtonType::LINK);
503 |      * ```
504 |      */
505 |     public function type(ButtonType $type): self
506 |     {
507 |         $new = clone $this;
508 |         $new->tag = match ($type) {
509 |             ButtonType::LINK => A::tag(),
510 |             ButtonType::RESET => ButtonTag::reset(''),
511 |             ButtonType::RESET_INPUT => Input::resetButton(),
512 |             ButtonType::SUBMIT => ButtonTag::submit(''),
513 |             ButtonType::SUBMIT_INPUT => Input::submitButton(),
514 |         };
515 | 
516 |         return $new;
517 |     }
518 | 
519 |     /**
520 |      * Sets the URL of the link.
521 |      *
522 |      * @param string|null $url The URL of the link.
523 |      *
524 |      * @return self A new instance with the specified URL.
525 |      *
526 |      * Example usage:
527 |      * ```php
528 |      * $button->url('/path/to/page');
529 |      * ```
530 |      */
531 |     public function url(string|null $url): self
532 |     {
533 |         return $this->attribute('href', $url);
534 |     }
535 | 
536 |     /**
537 |      * Set the variant.
538 |      *
539 |      * @param ButtonVariant|null $variant The variant. If `null`, the variant will not be set.
540 |      *
541 |      * @return self A new instance with the specified variant.
542 |      *
543 |      * Example usage:
544 |      * ```php
545 |      * $button->variant(ButtonVariant::PRIMARY);
546 |      * ```
547 |      */
548 |     public function variant(ButtonVariant|null $variant): self
549 |     {
550 |         $new = clone $this;
551 |         $new->buttonVariant = $variant;
552 | 
553 |         return $new;
554 |     }
555 | 
556 |     /**
557 |      * Run the widget.
558 |      *
559 |      * @return string The HTML representation of the element.
560 |      */
561 |     public function render(): string
562 |     {
563 |         $attributes = $this->attributes;
564 |         $classes = $attributes['class'] ?? null;
565 |         $tag = $this->tag ?? ButtonTag::tag()->button('');
566 | 
567 |         unset($attributes['class'], $attributes['id']);
568 | 
569 |         Html::addCssClass($attributes, [self::NAME, $this->buttonVariant?->value, $classes]);
570 | 
571 |         $attributes = $this->setAttributes($attributes);
572 |         $tag = $tag->addAttributes($attributes)->addClass(...$this->cssClasses)->id($this->getId());
573 | 
574 |         if ($tag instanceof Input) {
575 |             if ($this->label !== '') {
576 |                 $tag = $tag->value($this->label);
577 |             }
578 | 
579 |             return $tag->render();
580 |         }
581 | 
582 |         return $tag->addContent($this->label)->addClass()->encode(false)->render();
583 |     }
584 | 
585 |     /**
586 |      * Generates the ID.
587 |      *
588 |      * @return string|null The generated ID.
589 |      *
590 |      * @psalm-return non-empty-string|null The generated ID.
591 |      */
592 |     private function getId(): string|null
593 |     {
594 |         return match ($this->id) {
595 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
596 |             '', false => null,
597 |             default => $this->id,
598 |         };
599 |     }
600 | 
601 |     /**
602 |      * Sets the attributes for the button.
603 |      *
604 |      * @param array $attributes The attributes to set.
605 |      *
606 |      * @return array The updated attributes.
607 |      */
608 |     private function setAttributes(array $attributes): array
609 |     {
610 |         if ($this->disabled) {
611 |             $attributes['disabled'] = true;
612 | 
613 |             if ($this->tag instanceof A) {
614 |                 $attributes['aria-disabled'] = 'true';
615 | 
616 |                 unset($attributes['disabled']);
617 |                 Html::addCssClass($attributes, 'disabled');
618 |             }
619 |         }
620 | 
621 |         if ($this->tag instanceof A) {
622 |             $attributes['role'] ??= 'button';
623 |         }
624 | 
625 |         return $attributes;
626 |     }
627 | }
628 | 


--------------------------------------------------------------------------------
/src/Alert.php:
--------------------------------------------------------------------------------
  1 | <?php
  2 | 
  3 | declare(strict_types=1);
  4 | 
  5 | namespace Yiisoft\Bootstrap5;
  6 | 
  7 | use BackedEnum;
  8 | use InvalidArgumentException;
  9 | use Stringable;
 10 | use Yiisoft\Html\Html;
 11 | use Yiisoft\Html\Tag\Button;
 12 | use Yiisoft\Html\Tag\Div;
 13 | use Yiisoft\Widget\Widget;
 14 | 
 15 | use function array_key_exists;
 16 | use function preg_replace;
 17 | use function strtr;
 18 | 
 19 | /**
 20 |  * Alert renders an alert bootstrap component.
 21 |  *
 22 |  * For example,
 23 |  *
 24 |  * ```php
 25 |  * <?= Alert::widget()->body('Say hello...')->variant(AlertVariant::PRIMARY) ?>
 26 |  * ```
 27 |  *
 28 |  * @link https://getbootstrap.com/docs/5.0/components/alerts/
 29 |  */
 30 | final class Alert extends Widget
 31 | {
 32 |     private const CLASS_CLOSE_BUTTON = 'btn-close';
 33 | 
 34 |     private const NAME = 'alert';
 35 | 
 36 |     private array $attributes = [];
 37 | 
 38 |     private AlertVariant $alertType = AlertVariant::SECONDARY;
 39 | 
 40 |     private string|Stringable $body = '';
 41 | 
 42 |     private array $cssClasses = [];
 43 | 
 44 |     private array $closeButtonAttributes = [];
 45 | 
 46 |     private string|null $closeButtonTag = null;
 47 | 
 48 |     private string $closeButtonLabel = '';
 49 | 
 50 |     private bool $dismissable = false;
 51 | 
 52 |     private bool $fade = false;
 53 | 
 54 |     private string|null $header = null;
 55 | 
 56 |     private array $headerAttributes = [];
 57 | 
 58 |     private string $headerTag = 'h4';
 59 | 
 60 |     private bool|string $id = true;
 61 | 
 62 |     private string $templateContent = "\n{header}\n{body}\n{toggler}\n";
 63 | 
 64 |     /**
 65 |      * Adds a sets of attributes.
 66 |      *
 67 |      * @param array $attributes Attribute values indexed by attribute names. for example, `['id' => 'my-id']`.
 68 |      *
 69 |      * @return self A new instance with the specified attributes added.
 70 |      *
 71 |      * Example usage:
 72 |      * ```php
 73 |      * $alert->addAttributes(['data-id' => '123']);
 74 |      * ```
 75 |      */
 76 |     public function addAttributes(array $attributes): self
 77 |     {
 78 |         $new = clone $this;
 79 |         $new->attributes = [...$this->attributes, ...$attributes];
 80 | 
 81 |         return $new;
 82 |     }
 83 | 
 84 |     /**
 85 |      * Adds one or more CSS classes to the existing classes.
 86 |      *
 87 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
 88 |      * automatically.
 89 |      *
 90 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
 91 |      *
 92 |      * @return self A new instance with the specified CSS classes added to existing ones.
 93 |      *
 94 |      * @link https://html.spec.whatwg.org/#classes
 95 |      *
 96 |      * Example usage:
 97 |      * ```php
 98 |      * $alert->addClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
 99 |      * ```
100 |      */
101 |     public function addClass(BackedEnum|string|null ...$class): self
102 |     {
103 |         $new = clone $this;
104 |         $new->cssClasses = [...$this->cssClasses, ...$class];
105 | 
106 |         return $new;
107 |     }
108 | 
109 |     /**
110 |      * Adds close button attribute value.
111 |      *
112 |      * @param string $name The attribute name.
113 |      * @param mixed $value The attribute value.
114 |      *
115 |      * @return self A new instance with the specified attribute added.
116 |      *
117 |      * Example usage:
118 |      * ```php
119 |      * $alert->addCloseButtonAttribute('data-id', '123');
120 |      * ```
121 |      */
122 |     public function addCloseButtonAttribute(string $name, mixed $value): self
123 |     {
124 |         $new = clone $this;
125 |         $new->closeButtonAttributes[$name] = $value;
126 | 
127 |         return $new;
128 |     }
129 | 
130 |     /**
131 |      * Adds one or more CSS classes to the existing close button classes.
132 |      *
133 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
134 |      * automatically.
135 |      *
136 |      * @param BackedEnum|string|null ...$class One or more CSS class names to add. Pass `null` to skip adding a class.
137 |      *
138 |      * @return self A new instance with the specified CSS classes added to existing ones.
139 |      *
140 |      * @link https://html.spec.whatwg.org/#classes
141 |      *
142 |      * Example usage:
143 |      * ```php
144 |      * $alert->addCloseButtonClass('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
145 |      * ```
146 |      */
147 |     public function addCloseButtonClass(BackedEnum|string|null ...$class): self
148 |     {
149 |         $new = clone $this;
150 | 
151 |         foreach ($class as $item) {
152 |             Html::addCssClass($new->closeButtonAttributes, $item);
153 |         }
154 | 
155 |         return $new;
156 |     }
157 | 
158 |     /**
159 |      * Adds a close button CSS style.
160 |      *
161 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
162 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
163 |      * If it is a string, it will be added as is, for example, `color: red`.
164 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
165 |      * appended to the existing one.
166 |      *
167 |      * @return self A new instance with the specified CSS style value added.
168 |      *
169 |      * Example usage:
170 |      * ```php
171 |      * $alert->addCloseButtonCssStyle('color: red');
172 |      *
173 |      * // or
174 |      * $alert->addCloseButtonCssStyle(['color' => 'red', 'font-weight' => 'bold']);
175 |      * ```
176 |      */
177 |     public function addCloseButtonCssStyle(array|string $style, bool $overwrite = true): self
178 |     {
179 |         $new = clone $this;
180 |         Html::addCssStyle($new->closeButtonAttributes, $style, $overwrite);
181 | 
182 |         return $new;
183 |     }
184 | 
185 |     /**
186 |      * Adds a CSS style.
187 |      *
188 |      * @param array|string $style The CSS style. If the value is an array, a space will separate the values.
189 |      * For example, `['color' => 'red', 'font-weight' => 'bold']` will be rendered as `color: red; font-weight: bold;`.
190 |      * If it is a string, it will be added as is, for example, `color: red`.
191 |      * @param bool $overwrite Whether to overwrite existing styles with the same name. If `false`, the new value will be
192 |      * appended to the existing one.
193 |      *
194 |      * @return self A new instance with the specified CSS style value added.
195 |      *
196 |      * Example usage:
197 |      * ```php
198 |      * $alert->addCssStyle('color: red');
199 |      *
200 |      * // or
201 |      * $alert->addCssStyle(['color' => 'red', 'font-weight' => 'bold']);
202 |      * ```
203 |      */
204 |     public function addCssStyle(array|string $style, bool $overwrite = true): self
205 |     {
206 |         $new = clone $this;
207 |         Html::addCssStyle($new->attributes, $style, $overwrite);
208 | 
209 |         return $new;
210 |     }
211 | 
212 |     /**
213 |      * Adds a sets attribute value.
214 |      *
215 |      * @param string $name The attribute name.
216 |      * @param mixed $value The attribute value.
217 |      *
218 |      * @return self A new instance with the specified attribute added.
219 |      *
220 |      * Example usage:
221 |      * ```php
222 |      * $alert->attribute('data-id', '123');
223 |      * ```
224 |      */
225 |     public function attribute(string $name, mixed $value): self
226 |     {
227 |         $new = clone $this;
228 |         $new->attributes[$name] = $value;
229 | 
230 |         return $new;
231 |     }
232 | 
233 |     /**
234 |      * Sets the HTML attributes.
235 |      *
236 |      * @param array $attributes Attribute values indexed by attribute names.
237 |      *
238 |      * @return self A new instance with the specified attributes.
239 |      *
240 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
241 |      *
242 |      * Example usage:
243 |      * ```php
244 |      * $alert->attributes(['data-id' => '123']);
245 |      * ```
246 |      */
247 |     public function attributes(array $attributes): self
248 |     {
249 |         $new = clone $this;
250 |         $new->attributes = $attributes;
251 | 
252 |         return $new;
253 |     }
254 | 
255 |     /**
256 |      * Sets the body content.
257 |      *
258 |      * @param string|Stringable $content The body content.
259 |      * @param bool $encode Whether the body value should be HTML-encoded. Use this when rendering user-generated content
260 |      * to prevent XSS attacks.
261 |      *
262 |      * @return self A new instance with the specified body content.
263 |      *
264 |      * Example usage:
265 |      * ```php
266 |      * $alert->body('Say hello...');
267 |      * ```
268 |      */
269 |     public function body(string|Stringable $content, bool $encode = true): self
270 |     {
271 |         if ($encode) {
272 |             $content = Html::encode($content);
273 |         }
274 | 
275 |         $new = clone $this;
276 |         $new->body = $content;
277 | 
278 |         return $new;
279 |     }
280 | 
281 |     /**
282 |      * Replaces all existing CSS classes with the specified one(s).
283 |      *
284 |      * Multiple classes can be added by passing them as separate arguments. `null` values are filtered out
285 |      * automatically.
286 |      *
287 |      * @param BackedEnum|string|null ...$class One or more CSS class names to set. Pass `null` to skip setting a class.
288 |      *
289 |      * @return self A new instance with the specified CSS classes set.
290 |      *
291 |      * Example usage:
292 |      * ```php
293 |      * $alert->class('custom-class', null, 'another-class', BackGroundColor::PRIMARY);
294 |      * ```
295 |      */
296 |     public function class(BackedEnum|string|null ...$class): self
297 |     {
298 |         $new = clone $this;
299 |         $new->cssClasses = $class;
300 | 
301 |         return $new;
302 |     }
303 | 
304 |     /**
305 |      * Sets the HTML attributes for the close button.
306 |      *
307 |      * @param array $attributes Attribute values indexed by attribute names.
308 |      *
309 |      * @return self A new instance with the specified HTML attributes for the close button.
310 |      *
311 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
312 |      *
313 |      * Example usage:
314 |      * ```php
315 |      * $alert->closeButtonAttributes(['class' => 'my-class']);
316 |      * ```
317 |      */
318 |     public function closeButtonAttributes(array $attributes): self
319 |     {
320 |         $new = clone $this;
321 |         $new->closeButtonAttributes = $attributes;
322 | 
323 |         return $new;
324 |     }
325 | 
326 |     /**
327 |      * Sets the label for the close button.
328 |      *
329 |      * @param string $label The label for the close button.
330 |      *
331 |      * @return self A new instance with the specified close button label.
332 |      *
333 |      * Example usage:
334 |      * ```php
335 |      * $alert->closeButtonLabel('Close');
336 |      * ```
337 |      */
338 |     public function closeButtonLabel(string $label): self
339 |     {
340 |         $new = clone $this;
341 |         $new->closeButtonLabel = $label;
342 | 
343 |         return $new;
344 |     }
345 | 
346 |     /**
347 |      * Sets the HTML tag to be used for the close button.
348 |      *
349 |      * @param string $tag The HTML tag name for the close button.
350 |      *
351 |      * @return self A new instance with the specified close button tag.
352 |      *
353 |      * Example usage:
354 |      * ```php
355 |      * $alert->closeButtonTag('button');
356 |      * ```
357 |      */
358 |     public function closeButtonTag(string $tag): self
359 |     {
360 |         $new = clone $this;
361 |         $new->closeButtonTag = $tag;
362 | 
363 |         return $new;
364 |     }
365 | 
366 |     /**
367 |      * Makes the alert dismissible by adding a close button.
368 |      *
369 |      * @param bool $enabled Whether to make the alert dismissible.
370 |      *
371 |      * @return self A new instance with the specified dismissable value.
372 |      *
373 |      * Example usage:
374 |      * ```php
375 |      * $alert->dismissable(true);
376 |      * ```
377 |      */
378 |     public function dismissable(bool $enabled): self
379 |     {
380 |         $new = clone $this;
381 |         $new->dismissable = $enabled;
382 | 
383 |         return $new;
384 |     }
385 | 
386 |     /**
387 |      * Adds a fade effect.
388 |      *
389 |      * @param bool $enabled Whether to add a fade effect.
390 |      *
391 |      * @return self A new instance with the specified fade value.
392 |      *
393 |      * Example usage:
394 |      * ```php
395 |      * $alert->fade(true);
396 |      * ```
397 |      */
398 |     public function fade(bool $enabled): self
399 |     {
400 |         $new = clone $this;
401 |         $new->fade = $enabled;
402 | 
403 |         return $new;
404 |     }
405 | 
406 |     /**
407 |      * Sets the header content.
408 |      *
409 |      * @param string|null $content The header content.
410 |      * @param bool $encode Whether the body value should be HTML-encoded. Use this when rendering user-generated content
411 |      * to prevent XSS attacks.
412 |      *
413 |      * @return self A new instance with the specified header content.
414 |      *
415 |      * Example usage:
416 |      * ```php
417 |      * $alert->header('Header content');
418 |      * ```
419 |      */
420 |     public function header(string|null $content, bool $encode = true): self
421 |     {
422 |         if ($encode) {
423 |             $content = Html::encode($content);
424 |         }
425 | 
426 |         $new = clone $this;
427 |         $new->header = $content;
428 | 
429 |         return $new;
430 |     }
431 | 
432 |     /**
433 |      * Sets the HTML attributes for the header section.
434 |      *
435 |      * @param array $attributes Attribute values indexed by attribute names.
436 |      *
437 |      * @return self A new instance with the specified attributes for the header section.
438 |      *
439 |      * @see {\Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
440 |      *
441 |      * Example usage:
442 |      * ```php
443 |      * $alert->headerAttributes(['class' => 'my-class']);
444 |      * ```
445 |      */
446 |     public function headerAttributes(array $attributes): self
447 |     {
448 |         $new = clone $this;
449 |         $new->headerAttributes = $attributes;
450 | 
451 |         return $new;
452 |     }
453 | 
454 |     /**
455 |      * Sets the HTML tag to be used for the header section.
456 |      *
457 |      * @param string $tag The HTML tag name for the header section.
458 |      *
459 |      * @return self A new instance with the specified header tag.
460 |      *
461 |      * Example usage:
462 |      * ```php
463 |      * $alert->headerTag('h4');
464 |      * ```
465 |      */
466 |     public function headerTag(string $tag): self
467 |     {
468 |         $new = clone $this;
469 |         $new->headerTag = $tag;
470 | 
471 |         return $new;
472 |     }
473 | 
474 |     /**
475 |      * Sets the ID.
476 |      *
477 |      * @param bool|string $id The ID of the component. If `true`, an ID will be generated automatically.
478 |      *
479 |      * @return self A new instance with the specified ID.
480 |      *
481 |      * Example usage:
482 |      * ```php
483 |      * $alert->id('my-id');
484 |      * ```
485 |      */
486 |     public function id(bool|string $id): self
487 |     {
488 |         $new = clone $this;
489 |         $new->id = $id;
490 | 
491 |         return $new;
492 |     }
493 | 
494 |     /**
495 |      * Sets the template content to be used for rendering.
496 |      *
497 |      * @param string $content The template content string.
498 |      *
499 |      * @return self A new instance with the specified template content.
500 |      *
501 |      * Example usage:
502 |      * ```php
503 |      * $alert->templateContent("\n{header}\n{body}\n{toggler}\n");
504 |      * ```
505 |      */
506 |     public function templateContent(string $content): self
507 |     {
508 |         $new = clone $this;
509 |         $new->templateContent = $content;
510 | 
511 |         return $new;
512 |     }
513 | 
514 |     /**
515 |      * Set the alert variant.
516 |      *
517 |      * @param AlertVariant $variant The alert variant.
518 |      *
519 |      * @return self A new instance with the specified alert variant.
520 |      *
521 |      * Example usage:
522 |      * ```php
523 |      * $alert->variant(AlertVariant::PRIMARY);
524 |      * ```
525 |      */
526 |     public function variant(AlertVariant $variant): self
527 |     {
528 |         $new = clone $this;
529 |         $new->alertType = $variant;
530 | 
531 |         return $new;
532 |     }
533 | 
534 |     /**
535 |      * Run the widget.
536 |      *
537 |      * @return string The HTML representation of the element.
538 |      */
539 |     public function render(): string
540 |     {
541 |         $attributes = $this->attributes;
542 |         $attributes['role'] = self::NAME;
543 |         $toggler = '';
544 |         $classes = $attributes['class'] ?? null;
545 | 
546 |         unset($attributes['class'], $attributes['id']);
547 | 
548 |         Html::addCssClass($attributes, [self::NAME, $this->alertType->value, $classes, ...$this->cssClasses]);
549 | 
550 |         if ($this->dismissable) {
551 |             Html::addCssClass($attributes, 'alert-dismissible');
552 |             $toggler = $this->renderToggler();
553 |         }
554 | 
555 |         if ($this->fade) {
556 |             Html::addCssClass($attributes, 'fade show');
557 |         }
558 | 
559 |         $content = strtr(
560 |             $this->templateContent,
561 |             [
562 |                 '{header}' => $this->renderHeader(),
563 |                 '{body}' => $this->body,
564 |                 '{toggler}' => $toggler,
565 |             ]
566 |         );
567 | 
568 |         $content = preg_replace("/\n{2}/", "\n", $content) ?? '';
569 | 
570 |         return Div::tag()->addAttributes($attributes)->content($content)->encode(false)->id($this->getId())->render();
571 |     }
572 | 
573 |     /**
574 |      * Generates the ID.
575 |      *
576 |      * @return string|null The generated ID.
577 |      *
578 |      * @psalm-return non-empty-string|null The generated ID.
579 |      */
580 |     private function getId(): string|null
581 |     {
582 |         return match ($this->id) {
583 |             true => $this->attributes['id'] ?? Html::generateId(self::NAME . '-'),
584 |             '', false => null,
585 |             default => $this->id,
586 |         };
587 |     }
588 | 
589 |     /**
590 |      * Render the header.
591 |      *
592 |      * @throws InvalidArgumentException If the header tag is an empty string.
593 |      *
594 |      * @return string The HTML representation of the element.
595 |      */
596 |     private function renderHeader(): string
597 |     {
598 |         if ($this->header === null) {
599 |             return '';
600 |         }
601 | 
602 |         $headerAttributes = $this->headerAttributes;
603 | 
604 |         Html::addCssClass($headerAttributes, 'alert-heading');
605 | 
606 |         if ($this->headerTag === '') {
607 |             throw new InvalidArgumentException('Header tag cannot be empty string.');
608 |         }
609 | 
610 |         return Html::tag($this->headerTag, '', $headerAttributes)->content($this->header)->encode(false)->render();
611 |     }
612 | 
613 |     /**
614 |      * Renders the toggler.
615 |      *
616 |      * @throws InvalidArgumentException If the close button tag is an empty string.
617 |      *
618 |      * @return string The HTML representation of the element.
619 |      */
620 |     private function renderToggler(): string
621 |     {
622 |         $buttonTag = match ($this->closeButtonTag) {
623 |             null => Button::button(''),
624 |             '' => throw new InvalidArgumentException('Close button tag cannot be empty string.'),
625 |             default => Html::tag($this->closeButtonTag),
626 |         };
627 | 
628 |         $closeButtonAttributes = $this->closeButtonAttributes;
629 |         $classesButton = $closeButtonAttributes['class'] ?? null;
630 | 
631 |         unset($closeButtonAttributes['class']);
632 | 
633 |         $buttonTag = $buttonTag
634 |             ->addClass(self::CLASS_CLOSE_BUTTON, $classesButton)
635 |             ->addAttributes($closeButtonAttributes)
636 |             ->addContent($this->closeButtonLabel);
637 | 
638 |         if (array_key_exists('data-bs-dismiss', $closeButtonAttributes) === false) {
639 |             $buttonTag = $buttonTag->attribute('data-bs-dismiss', 'alert');
640 |         }
641 | 
642 |         if (array_key_exists('aria-label', $closeButtonAttributes) === false) {
643 |             $buttonTag = $buttonTag->attribute('aria-label', 'Close');
644 |         }
645 | 
646 |         return $buttonTag->render();
647 |     }
648 | }
649 | 


--------------------------------------------------------------------------------