README

impulsephp/story est l’explorateur visuel de composants d’ImpulsePHP. Le package permet de parcourir, prévisualiser et documenter les composants d’une application ou d’un package à partir de classes de story dédiées.

Ce que fait le package

scanne automatiquement les stories présentes dans l’application ;
expose une interface visuelle de prévisualisation ;
regroupe les stories par catégories ;
prend en charge plusieurs variantes par composant ;
charge les feuilles de style associées à l’explorateur.

Prérequis

PHP 8.2 ou supérieur ;
une application ImpulsePHP avec impulsephp/core ;
Node.js si vous souhaitez reconstruire les assets CSS du package.

Installation

composer require impulsephp/story

Le provider est déclaré via extra.impulse-provider. Si l’auto-découverte n’est pas utilisée, ajoutez Impulse\Story\StoryProvider à votre configuration de providers.

Ce que fait le provider

Le provider :

enregistre Impulse\Story\Loader\StoryScanner dans le conteneur ;
expose les routes de page du package ;
déclare les espaces de noms de composants de story ;
charge les chemins CSS définis dans la configuration css.

L’explorateur principal est exposé par défaut sur :

/impulse/story

Où placer vos stories

Le scanner ajoute automatiquement ces chemins :

src/Story
tests/Stories

Chaque fichier PHP rencontré dans ces répertoires est analysé. Si la classe implémente Impulse\Story\Contracts\StoryInterface, elle est chargée et ajoutée à l’explorateur.

Exemple d’usage complet

Le package fournit une classe abstraite Impulse\Story\Component\AbstractStory qui simplifie la création d’une story.

use Impulse\Story\Component\AbstractStory;
use App\Component\ButtonComponent;

final class ButtonStory extends AbstractStory
{
    protected string $category = 'Actions';

    public function name(): string
    {
        return 'Button';
    }

    public function description(): string
    {
        return 'Variantes du bouton principal de l’application.';
    }

    public function componentClass(): string
    {
        return ButtonComponent::class;
    }

    protected function getBaseArgs(): array
    {
        return [
            'label' => 'Créer',
            'color' => 'indigo',
        ];
    }

    public function variants(): array
    {
        return [
            'primaire' => ['label' => 'Créer'],
            'danger' => ['label' => 'Supprimer', 'color' => 'red'],
        ];
    }
}

Une fois le provider chargé :

placez vos stories dans src/Story ou tests/Stories ;
démarrez votre application ;
ouvrez /impulse/story dans le navigateur.

Exploiter le scanner depuis le code

use Impulse\Story\Loader\StoryScanner;

$scanner = $container->get(StoryScanner::class);

$menu = $scanner->getMenuStructure();
$stories = $scanner->getStoriesByCategory();
$story = $scanner->getStoryByName('Button');

Assets CSS

Le package contient des assets CSS et un script npm pour surveiller la compilation :

npm install
npm run watch:css

La commande compile assets/css/main.css vers public/css/main.css.

Aller plus loin

impulsephp/story est particulièrement utile avec :

impulsephp/ui, qui fournit déjà des stories prêtes à l’emploi ;
vos composants applicatifs pour documenter variantes et états de rendu.

Tests

composer test

Licence

MIT

impulsephp / story

Maintainers

Package info

Statistics

Security