README

Core UX foundations for Krystal Symfony UX Projects: base component class, composable traits, presets dictionaries and Twig globals.

Installation

composer require krystal-sf/ux-common

Enable the bundle in config/bundles.php:

return [
    // ...
    Ksf\Core\UxCommon\KsfUxCommonBundle::class => ['all' => true],
];

Writing a Krystal Component

All Krystal Twig & Live components extend AbstractUxComponent, a plain class composed of traits (it does NOT extend AbstractController):

use Ksf\Core\UxCommon\Twig\AbstractUxComponent;
use Symfony\UX\TwigComponent\Attribute\AsTwigComponent;

#[AsTwigComponent(name: 'Acme:MyCard', template: '@AcmeBundle/components/card.html.twig')]
class MyCard extends AbstractUxComponent
{
}

Available Traits

Trait	Purpose
`ComponentWithContentsTrait`	Standard content props: `title`, `subtitle`, `icon`, `text`, `class`...
`ComponentWithTranslationsTrait`	Auto-translation of registered props (`translationDomain`)
`ComponentWithAutoloadTrait`	Autoload of props from translations (`autoload` key)
`ComponentWithPresetTrait`	Presets application (`presets` prop + `AsPresetProcessor` services)
`ComponentWithRouterTrait`	Router access & URL generation
`ComponentWithLinkTrait`	Link props: `route`, `url`, `anchor`, `jumpTo`
`ComponentWithAlternateTrait`	Alternate flag for even/odd items rendering (opt-in)
`ComponentWithFlashesTrait`	Session flash messages from components (opt-in)
`ComponentWithExecuteTrait`	Live action forwarding to controllers (opt-in, not in base class)
`ComponentWithControllerActionTrait`	Encode controller actions for live components (opt-in)

NB: ComponentWithActionTrait (Knp Menu action props) lives in krystal-sf/ux-menus, to keep this package free of menus dependencies.

Presets & Dictionaries

Dictionaries expose their constants as the ux.* Twig global (via GlobalsVariablesCompiler):

<twig:Ksf:Alert presets="{{ [ux.presets.alerts.types.SUCCESS] }}"/>

Declare your own dictionaries with the provided attributes:

#[AsGlobalDictionary("name")] → ux.name.*
#[AsPresetsDictionary("name")] → ux.presets.name.*
#[AsRoutesDictionary("name")] → ux.routes.name.*

Available presets dictionaries: AlertsTypesPresets, AlertsSizePresets, BtnStylesPresets, BtnSizesPresets, BtnFormatsPresets, CardsStylesPresets, CardsPlainStylesPresets.

Events dictionaries (PHP constants mirrored in templates via data attributes): ModalEvents, FlashBagEvents, ActionContext.

Stimulus & Assets

The package ships an importmap bridge (@krystal-sf/ux-common) that exposes jQuery globally for legacy libraries. Stimulus controllers of all Krystal packages are declared through the standard symfony.controllers convention: they are registered by the HOST application's Stimulus app — no global Stimulus instance is ever started by Krystal packages.

Profiler

In dev environment, the GlobalsCollector adds a "Krystal UX" entry to the debug toolbar AND a full profiler panel showing all ux.* globals exposed to Twig — click any key or value to copy it to the clipboard.

Testing

make phpunit          # run package tests
make verify           # containers + deps + quality + tests, all Symfony versions

License

MIT — see LICENSE.

krystal-sf / ux-common

Maintainers

Package info

Statistics

Security