[Toolkit] Rework kits architecture, change term for "recipe"

Author: Kocal

src/Toolkit/bin/ux-toolkit-kit-debug

@@ -22,6 +22,7 @@ use Symfony\Contracts\Service\ServiceProviderInterface;
 use Symfony\UX\Toolkit\Command\DebugKitCommand;
 use Symfony\UX\Toolkit\Kit\KitSynchronizer;
 use Symfony\UX\Toolkit\Kit\KitFactory;
+use Symfony\UX\Toolkit\Recipe\RecipeSynchronizer;
 use Symfony\UX\Toolkit\Registry\GitHubRegistry;
 use Symfony\UX\Toolkit\Registry\LocalRegistry;
 use Symfony\UX\Toolkit\Registry\RegistryFactory;
@@ -46,7 +47,8 @@ if (!class_exists(Application::class)) {
 }
 
 $filesystem = new Filesystem();
-$kitFactory = new KitFactory($filesystem, new KitSynchronizer($filesystem));
+$kitSynchronizer = new KitSynchronizer($filesystem, new RecipeSynchronizer($filesystem));
+$kitFactory = new KitFactory($filesystem, $kitSynchronizer);
 
 (new Application())->add($command = new DebugKitCommand($kitFactory))
     ->getApplication()

src/Toolkit/config/services.php

@@ -11,11 +11,13 @@
 
 namespace Symfony\Component\DependencyInjection\Loader\Configurator;
 
+use Symfony\UX\Toolkit\Command\CreateKitCommand;
 use Symfony\UX\Toolkit\Command\DebugKitCommand;
-use Symfony\UX\Toolkit\Command\InstallComponentCommand;
+use Symfony\UX\Toolkit\Command\InstallCommand;
 use Symfony\UX\Toolkit\Kit\KitContextRunner;
 use Symfony\UX\Toolkit\Kit\KitFactory;
 use Symfony\UX\Toolkit\Kit\KitSynchronizer;
+use Symfony\UX\Toolkit\Recipe\RecipeSynchronizer;
 use Symfony\UX\Toolkit\Registry\GitHubRegistry;
 use Symfony\UX\Toolkit\Registry\LocalRegistry;
 use Symfony\UX\Toolkit\Registry\RegistryFactory;
@@ -34,7 +36,13 @@
             ])
             ->tag('console.command')
 
-        ->set('.ux_toolkit.command.install', InstallComponentCommand::class)
+        ->set('.ux_toolkit.command.create_kit', CreateKitCommand::class)
+            ->args([
+                service('filesystem'),
+            ])
+            ->tag('console.command')
+
+        ->set('.ux_toolkit.command.install', InstallCommand::class)
             ->args([
                 service('.ux_toolkit.registry.registry_factory'),
                 service('filesystem'),
@@ -75,6 +83,7 @@
         ->set('.ux_toolkit.kit.kit_synchronizer', KitSynchronizer::class)
             ->args([
                 service('filesystem'),
+                service('.ux_toolkit.recipe.recipe_synchronizer'),
             ])
 
         ->set('ux_toolkit.kit.kit_context_runner', KitContextRunner::class)
@@ -83,5 +92,7 @@
                 service('twig'),
                 service('ux.twig_component.component_factory'),
             ])
+
+        ->set('.ux_toolkit.recipe.recipe_synchronizer', RecipeSynchronizer::class)
     ;
 };

src/Toolkit/doc/index.rst

@@ -7,26 +7,24 @@ to change, or even change drastically.
 Symfony UX Toolkit provides a set of ready-to-use kits for Symfony applications.
 It is part of `the Symfony UX initiative`_.
 
-Kits are a nice way to begin a new Symfony application, by providing a set
-of `Twig components`_ (based on Tailwind CSS, but fully customizable depending
-on your needs).
+Kits are a nice way to begin a new Symfony application, they contains
+recipes to install nicely-crafter `Twig components`_ (already stylized,
+but fully customizable depending on your needs) and more.
 
 Please note that the **UX Toolkit is not a library of UI components**,
 but **a tool to help you build your own UI components**.
 It uses the same approach than the popular `Shadcn UI`_,
 and a similar approach than `Tailwind Plus`_.
 
-After installing the UX Toolkit, you can start pulling the components you need
-from `UX Toolkit Kits`_, and use them in your project.
-They become **your own components**, and **you can customize them as you want**.
+After installing the UX Toolkit, you can start installing the recipes you need
+from `UX Toolkit Kits`_ and use them in your project.
+Files created by the recipes become part of your project, and
+you can customize them as you want.
 
 Additionally, some `Twig components`_ use ``html_cva`` and ``tailwind_merge``,
 you can either remove them from your project or install ``twig/html-extra``
 and ``tales-from-a-dev/twig-tailwind-extra`` to use them.
 
-Also, we do not force you to use Tailwind CSS at all. You can use whatever
-CSS framework you want, but you will need to adapt the UI components to it.
-
 Installation
 ------------
 
@@ -37,27 +35,25 @@ Install the UX Toolkit using Composer and Symfony Flex:
     # The UX Toolkit is a development dependency:
     $ composer require --dev symfony/ux-toolkit
 
-    # If you want to keep `html_cva` and `tailwind_merge` in your Twig components:
-    $ composer require twig/extra-bundle twig/html-extra:^3.12.0 tales-from-a-dev/twig-tailwind-extra
-
 Usage
 -----
 
-You may find a list of components in the `UX Components page`_, with the installation instructions for each of them.
+You may find a list of available kits in the `UX Toolkit Kits`_ page, with the installation instructions for each of them.
 
 For example, if you want to install a `Button` component, you will find the following instruction:
 
 .. code-block:: terminal
 
-    $ php bin/console ux:toolkit:install-component Button --kit=<kitName>
+    $ php bin/console ux:install Button --kit=<kitName>
 
-It will create the ``templates/components/Button.html.twig`` file, and you will be able to use the `Button` component like this:
+It will create the ``templates/components/Button.html.twig`` file in your project,
+and you will be able to use the `Button` component like this:
 
 .. code-block:: html+twig
 
     <twig:Button>Click me</twig:Button>
 
-Create your own kit
+Create your own Kit
 -------------------
 
 You have the ability to create and share your own kit with the community,
@@ -96,19 +92,55 @@ After creating your kit, the repository should have the following structure:
 .. code-block:: text
 
     .
-    ├── docs
-    │   └── components
-    │       └── Button.twig
-    ├── manifest.json
-    └── templates
-        └── components
-            └── Button.html.twig
-
-A kit is composed of:
-
-- A ``manifest.json`` file, that describes the kit (name, license, homepage, authors, ...),
-- A ``templates/components`` directory, that contains the Twig components,
-- A ``docs/components`` directory, optional, that contains the documentation for each "root" Twig component.
+    ├── Button
+    │   ├── manifest.json
+    │   └── templates
+    │       └── components
+    │           └── Button.html.twig
+    └── manifest.json
+
+
+A kit is described by a ``manifest.json`` file at the root directory, which contains the metadata of the kit:
+
+.. code-block:: json
+
+    {
+        "$schema": "../vendor/symfony/ux-toolkit/schema-kit-v1.json",
+        "name": "My UX Toolkit Kit",
+        "description": "A custom kit for Symfony UX Toolkit.",
+        "homepage": "https://github/com/User/MyUxToolkitKit",
+        "license": "MIT"
+    }
+
+Then, a kit can contain one or more recipes. Each recipe is a directory
+with a ``manifest.json`` file and some files to be copied into the project.
+
+The ``manifest.json`` file of a recipe contains the metadata of the recipe:
+
+.. code-block:: json
+
+    {
+        "$schema": "../vendor/symfony/ux-toolkit/schema-kit-recipe-v1.json",
+        "name": "Button",
+        "description": "A clickable element that triggers actions or events, supporting various styles and states.",
+        "copy-files": {
+            "templates/": "templates/"
+        },
+        "dependencies": {
+            {
+                "type": "php",
+                "package": "twig/extra-bundle"
+            },
+            {
+                "type": "php",
+                "package": "twig/html-extra:^3.12.0"
+            },
+            {
+                "type": "php",
+                "package": "tales-from-a-dev/twig-tailwind-extra"
+            }
+        }
+    }
 
 Using your kit
 ~~~~~~~~~~~~~~
@@ -117,10 +149,10 @@ Once your kit is published on GitHub, you can use it by specifying the ``--kit``
 
 .. code-block:: terminal
 
-    $ php bin/console ux:toolkit:install-component Button --kit=github.com/my-username/my-ux-toolkit-kit
+    $ php bin/console ux:install Button --kit=github.com/my-username/my-ux-toolkit-kit
 
     # or for a specific version
-    $ php bin/console ux:toolkit:install-component Button --kit=github.com/my-username/my-ux-toolkit-kit:1.0.0
+    $ php bin/console ux:install Button --kit=github.com/my-username/my-ux-toolkit-kit:1.0.0
 
 Backward Compatibility promise
 ------------------------------

src/Toolkit/kits/shadcn/docs/components/Alert.md renamed to src/Toolkit/kits/shadcn/Alert/EXAMPLES.md

@@ -1,6 +1,6 @@
-# Alert
+# Examples
 
-A notification component that displays important messages with an icon, title, and description.
+## Default
 
 ```twig {"preview":true}
 <twig:Alert class="max-w-lg">
@@ -12,29 +12,7 @@ A notification component that displays important messages with an icon, title, a
 </twig:Alert>
 ```
 
-## Installation
-
-<!-- Placeholder: Installation -->
-
-## Usage
-
-<!-- Placeholder: Usage -->
-
-## Examples
-
-### Default
-
-```twig {"preview":true}
-<twig:Alert class="max-w-lg">
-    <twig:ux:icon name="tabler:terminal" class="h-4 w-4" />
-    <twig:Alert:Title>Heads up!</twig:Alert:Title>
-    <twig:Alert:Description>
-        You can add components to your app using the cli.
-    </twig:Alert:Description>
-</twig:Alert>
-```
-
-### Destructive
+## Destructive
 
 ```twig {"preview":true}
 <twig:Alert variant="destructive" class="max-w-lg">

src/Toolkit/kits/shadcn/templates/components/Separator.meta.json renamed to src/Toolkit/kits/shadcn/Alert/manifest.json

@@ -1,5 +1,11 @@
 {
-    "$schema": "../../../../schemas/component.json",
+    "$schema": "../../../schema-kit-recipe-v1.json",
+    "type": "component",
+    "name": "Alert",
+    "description": "A notification component that displays important messages with an icon, title, and description.",
+    "copy-files": {
+        "templates/": "templates/"
+    },
     "dependencies": [
         {
             "type": "php",

src/Toolkit/kits/shadcn/templates/components/Alert.html.twig renamed to src/Toolkit/kits/shadcn/Alert/templates/components/Alert.html.twig

@@ -1,6 +1,6 @@
-# AspectRatio
+# Examples
 
-A container that maintains a specific width-to-height ratio for its content.
+## Default
 
 ```twig {"preview":true,"height":"400px"}
 <twig:AspectRatio ratio="1 / 1" class="max-w-[300px]">
@@ -12,17 +12,7 @@ A container that maintains a specific width-to-height ratio for its content.
 </twig:AspectRatio>
 ```
 
-## Installation
-
-<!-- Placeholder: Installation -->
-
-## Usage
-
-<!-- Placeholder: Usage -->
-
-## Examples
-
-### With a 1 / 1 aspect ratio
+## With a 1 / 1 aspect ratio
 
 ```twig {"preview":true,"height":"400px"}
 <twig:AspectRatio ratio="1 / 1" class="max-w-[350px]">
@@ -34,7 +24,7 @@ A container that maintains a specific width-to-height ratio for its content.
 </twig:AspectRatio>
 ```
 
-### With a 16 / 9 aspect ratio
+## With a 16 / 9 aspect ratio
 
 ```twig {"preview":true,"height":"400px"}
 <twig:AspectRatio ratio="16 / 9" class="max-w-[350px]">

src/Toolkit/kits/shadcn/templates/components/Alert/Description.html.twig renamed to src/Toolkit/kits/shadcn/Alert/templates/components/Alert/Description.html.twig

@@ -0,0 +1,15 @@
+{
+    "$schema": "../../../schema-kit-recipe-v1.json",
+    "type": "component",
+    "name": "AspectRatio",
+    "description": "A container that maintains a specific width-to-height ratio for its content.",
+    "copy-files": {
+        "templates/": "templates/"
+    },
+    "dependencies": [
+        {
+            "type": "php",
+            "package": "twig/extra-bundle"
+        }
+    ]
+}