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é :

1. placez vos stories dans src/Story ou tests/Stories ;
2. démarrez votre application ;
3. 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