feature #2986 [Toolkit] Rework kits architecture, change term for "recipe" (Kocal)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

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

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes <!-- please update src/**/CHANGELOG.md files -->
| Docs?         | no <!-- required for new features -->
| Issues        | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

<!--
Replace this notice by a description of your feature/bugfix.
This will help reviewers and should be a good start for the documentation.

Additionally (see https://symfony.com/releases):
 - Always add tests and ensure they pass.
 - For new features, provide some code snippets to help understand usage.
 - Features and deprecations must be submitted against branch main.
 - Update/add documentation as required (we can help!)
 - Changelog entry should follow https://symfony.com/doc/current/contributing/code/conventions.html#writing-a-changelog-entry
 - Never break backward compatibility (see https://symfony.com/bc).
-->

This big PR modify the kits architecture from Toolkit, I get a lot of inspiration from Symfony Recipes and I think we are on something really really good.

The actual architecture was too coupled to a Symfony application structure, which made things easy for the website but not for working on "Recipes" (previously known as Components").

Before:
```
➜  Toolkit git:(2.x) tree kits/shadcn/
kits/shadcn/
├── AspectRatio
│   └── examples
├── docs
│   └── components
│       ├── Alert.md
│       ├── AspectRatio.md
│       ├── Avatar.md
│       ├── Badge.md
│       ├── Breadcrumb.md
│       ├── Button.md
│       ├── Card.md
│       ├── Checkbox.md
│       ├── Input.md
│       ├── Label.md
│       ├── Pagination.md
│       ├── Progress.md
│       ├── Select.md
│       ├── Separator.md
│       ├── Skeleton.md
│       ├── Switch.md
│       ├── Table.md
│       └── Textarea.md
├── INSTALL.md
├── manifest.json
└── templates
    └── components
        ├── Alert
        │   ├── Description.html.twig
        │   ├── Description.meta.json
        │   ├── Title.html.twig
        │   └── Title.meta.json
        ├── Alert.html.twig
        ├── Alert.meta.json
        ├── AspectRatio.html.twig
        ├── AspectRatio.meta.json
        ├── Avatar
        │   ├── Image.html.twig
        │   ├── Image.meta.json
        │   ├── Text.html.twig
        │   └── Text.meta.json
        ├── Avatar.html.twig
        ├── Avatar.meta.json
        ├── Badge.html.twig
        ├── Badge.meta.json
        ├── Breadcrumb
        │   ├── Ellipsis.html.twig
        │   ├── Ellipsis.meta.json
        │   ├── Item.html.twig
        │   ├── Item.meta.json
        │   ├── Link.html.twig
        │   ├── Link.meta.json
        │   ├── List.html.twig
        │   ├── List.meta.json
        │   ├── Page.html.twig
        │   ├── Page.meta.json
        │   ├── Separator.html.twig
        │   └── Separator.meta.json
        ├── Breadcrumb.html.twig
        ├── Breadcrumb.meta.json
        ├── Button.html.twig
        ├── Button.meta.json
        ├── Card
        │   ├── Content.html.twig
        │   ├── Content.meta.json
        │   ├── Description.html.twig
        │   ├── Description.meta.json
        │   ├── Footer.html.twig
        │   ├── Footer.meta.json
        │   ├── Header.html.twig
        │   ├── Header.meta.json
        │   ├── Title.html.twig
        │   └── Title.meta.json
        ├── Card.html.twig
        ├── Card.meta.json
        ├── Checkbox.html.twig
        ├── Checkbox.meta.json
        ├── Input.html.twig
        ├── Input.meta.json
        ├── Label.html.twig
        ├── Label.meta.json
        ├── Pagination
        │   ├── Content.html.twig
        │   ├── Content.meta.json
        │   ├── Ellipsis.html.twig
        │   ├── Ellipsis.meta.json
        │   ├── Item.html.twig
        │   ├── Item.meta.json
        │   ├── Link.html.twig
        │   ├── Link.meta.json
        │   ├── Next.html.twig
        │   ├── Next.meta.json
        │   ├── Previous.html.twig
        │   └── Previous.meta.json
        ├── Pagination.html.twig
        ├── Pagination.meta.json
        ├── Progress.html.twig
        ├── Progress.meta.json
        ├── Select.html.twig
        ├── Select.meta.json
        ├── Separator.html.twig
        ├── Separator.meta.json
        ├── Skeleton.html.twig
        ├── Skeleton.meta.json
        ├── Switch.html.twig
        ├── Switch.meta.json
        ├── Table
        │   ├── Body.html.twig
        │   ├── Body.meta.json
        │   ├── Caption.html.twig
        │   ├── Caption.meta.json
        │   ├── Cell.html.twig
        │   ├── Cell.meta.json
        │   ├── Footer.html.twig
        │   ├── Footer.meta.json
        │   ├── Head.html.twig
        │   ├── Head.meta.json
        │   ├── Header.html.twig
        │   ├── Header.meta.json
        │   ├── Row.html.twig
        │   └── Row.meta.json
        ├── Table.html.twig
        ├── Table.meta.json
        ├── Textarea.html.twig
        └── Textarea.meta.json
```

after:
```
➜  Toolkit git:(toolkit-rework-component-for-recipe) tree kits/shadcn/
├── Alert
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Alert
│           │   ├── Description.html.twig
│           │   └── Title.html.twig
│           └── Alert.html.twig
├── AspectRatio
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── AspectRatio.html.twig
├── Avatar
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Avatar
│           │   ├── Image.html.twig
│           │   └── Text.html.twig
│           └── Avatar.html.twig
├── Badge
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Badge.html.twig
├── Breadcrumb
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Breadcrumb
│           │   ├── Ellipsis.html.twig
│           │   ├── Item.html.twig
│           │   ├── Link.html.twig
│           │   ├── List.html.twig
│           │   ├── Page.html.twig
│           │   └── Separator.html.twig
│           └── Breadcrumb.html.twig
├── Button
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Button.html.twig
├── Card
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Card
│           │   ├── Content.html.twig
│           │   ├── Description.html.twig
│           │   ├── Footer.html.twig
│           │   ├── Header.html.twig
│           │   └── Title.html.twig
│           └── Card.html.twig
├── Checkbox
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Checkbox.html.twig
├── Input
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Input.html.twig
├── INSTALL.md
├── Label
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Label.html.twig
├── manifest.json
├── Pagination
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Pagination
│           │   ├── Content.html.twig
│           │   ├── Ellipsis.html.twig
│           │   ├── Item.html.twig
│           │   ├── Link.html.twig
│           │   ├── Next.html.twig
│           │   └── Previous.html.twig
│           └── Pagination.html.twig
├── Progress
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Progress.html.twig
├── Select
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Select.html.twig
├── Separator
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Separator.html.twig
├── Skeleton
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Skeleton.html.twig
├── Switch
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           └── Switch.html.twig
├── Table
│   ├── EXAMPLES.md
│   ├── manifest.json
│   └── templates
│       └── components
│           ├── Table
│           │   ├── Body.html.twig
│           │   ├── Caption.html.twig
│           │   ├── Cell.html.twig
│           │   ├── Footer.html.twig
│           │   ├── Head.html.twig
│           │   ├── Header.html.twig
│           │   └── Row.html.twig
│           └── Table.html.twig
└── Textarea
    ├── EXAMPLES.md
    ├── manifest.json
    └── templates
        └── components
            └── Textarea.html.twig

```

Now, everything under `kits/*/` **is a recipe**. There is no `Asset\Component` nor `Asset\StimulusController` anymore, everything was simplified a lot.

A Recipe:
- requires more files, but the organization is really better and more extensible
- has a `manifest.json` file, for describing its name, description, some dependencies (either PHP packages or other **Recipes**, which files to copy (and where), its **type** (either a `component`, or something else in the future), etc...
- has a `EXAMPLES.md` file, it's mainly internal for the Website

The CLI still works as expected:

https://github.com/user-attachments/assets/e954b783-b27a-4ffb-a3e8-e30621b667c2

The website too:

https://github.com/user-attachments/assets/4353dbba-8052-499e-a658-2e6ca6b5f39f

Commits
-------

39fb692 [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"
+        }
+    ]
+}