README

Html Core Component

Composable, immutable PHP primitives for building UI components: alerts, breadcrumbs, dropdowns, navbars, toggles, and menu items.
Accessible by default, fluent API, framework-friendly data hooks, and rendering powered by html-core.

Features

Installation

composer require ui-awesome/html-core-component:^0.2

Quick start

This package ships both abstract base classes (for subclassing) and ready-to-use concrete classes (Alert, Breadcrumb, Dropdown, NavBar, Toggle, Item, Menu). The concrete classes can be used directly via ::tag() without any subclassing.

The exposed abstractions are:

BaseAlert / Alert dismissible alerts with prefix/suffix containers and an optional toggle.
BaseBreadcrumb / Breadcrumb accessible breadcrumb navigation with active-path detection.
BaseDropdown / Dropdown dropdown menus with toggles, dividers, and active-link wiring.
BaseNavBar / NavBar navigation bars with brand, menu, and collapsible toggle.
BaseToggle / Toggle button or link toggles with full data-attribute coverage (Bootstrap, Flowbite, Tailwind UI).

Custom breadcrumb

use UIAwesome\Html\Core\Component\{BaseBreadcrumb, Item};

final class Breadcrumb extends BaseBreadcrumb {}

echo Breadcrumb::tag()
    ->items(
        Item::tag()->label('Home')->link('/'),
        Item::tag()->label('Library')->link('/library'),
        Item::tag()->label('Data')->active(true),
    )
    ->currentPath('/library')
    ->render();

Custom dropdown

use UIAwesome\Html\Core\Component\{BaseDropdown, Item};

final class Dropdown extends BaseDropdown {}

echo Dropdown::tag()
    ->items(
        Item::tag()->label('Profile')->link('/profile'),
        Item::tag()->label('Settings')->link('/settings'),
        Item::tag()->divider('<hr>'),
        Item::tag()->label('Sign out')->link('/logout'),
    )
    ->render();

Custom navbar with toggle

use UIAwesome\Html\Core\Component\{BaseNavBar, BaseToggle, Item};

final class NavBar extends BaseNavBar {}
final class Toggle extends BaseToggle {}

echo NavBar::tag()
    ->brandText('My App')
    ->brandLink('/')
    ->menu(
        Item::tag()->label('Home')->link('/'),
        Item::tag()->label('About')->link('/about'),
    )
    ->render();

Menu with wrapped labels

Each item label can be wrapped in its own element (for styling or truncation) via labelTag/labelClass. Without labelTag, the label renders as plain text.

use UIAwesome\Html\Core\Component\{Item, Menu};
use UIAwesome\Html\Interop\Inline;

echo Menu::tag()
    ->type('nav')
    ->linkClass('nav-link')
    ->linkActiveClass('is-active')
    ->items(
        Item::tag()
            ->label('Request')
            ->link('/request')
            ->active()
            ->labelTag(Inline::SPAN)
            ->labelClass('nav-link-label'),
        Item::tag()
            ->label('Logs')
            ->link('/logs')
            ->labelTag(Inline::SPAN)
            ->labelClass('nav-link-label'),
    )
    ->render();

Cookbooks (Bootstrap5, Flowbite)

The core ships preconfigured cookbooks for popular CSS frameworks under src/Cookbook/. Each cookbook implements one of the provider interfaces shipped by ui-awesome/html-core:

DefaultsProviderInterface::getDefaults(BaseTag $tag): array; applied via addDefaultProvider(ProviderClass::class). Used for cookbooks without variants.
ThemeProviderInterface::apply(BaseTag $tag, string $theme): array; applied via addThemeProvider('variant', ProviderClass::class). Used for cookbooks with multiple variants (danger, info, warning, ...).

use UIAwesome\Html\Core\Component\Alert;
use UIAwesome\Html\Core\Component\Cookbook\Bootstrap5\Alert\Defaults as BootstrapAlert;
use UIAwesome\Html\Core\Component\Cookbook\Flowbite\Alert\Defaults as FlowbiteAlert;

// 1. Bootstrap5 danger alert (theme provider variant is the theme name)
echo Alert::tag()
    ->addThemeProvider('danger', BootstrapAlert::class)
    ->content('Watch out!')
    ->render();

// 2. Flowbite info alert
echo Alert::tag()
    ->addThemeProvider('info', FlowbiteAlert::class)
    ->content('Heads up!')
    ->render();

// 3. Single-variant cookbook (default provider)
use UIAwesome\Html\Core\Component\Cookbook\Bootstrap5\Breadcrumb\Defaults as BreadcrumbDefaults;

echo Breadcrumb::tag()
    ->addDefaultProvider(BreadcrumbDefaults::class)
    ->items(/* ... */)
    ->render();

Available cookbooks (all under UIAwesome\Html\Core\Component\Cookbook):

Bootstrap5 Alert\{Defaults, Dismissible} (8 themes each), Breadcrumb\Defaults, Dropdown\{Defaults, Language}, NavBar\{Defaults, AlignRight}, Toggle\{Alert, Dropdown, Menu, MenuDropdown, SelectorLanguage, SelectorTheme}.
Flowbite Alert\{Defaults, Dismissible} (5 themes each), Breadcrumb\Defaults, Dropdown\{Defaults, Language} (5 themes each), NavBar\Defaults, Toggle\{Alert, Dropdown, Menu, MenuDropdown, SelectorLanguage, SelectorTheme}.

Authoring a new cookbook is a final class implementing DefaultsProviderInterface (single variant) or ThemeProviderInterface (multiple variants); both return a cookbook-style associative array of fluent method names mapped to their arguments.