Skip to content

Commit abc3d74

Browse files
KocalKocal
committed
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"
2 parents 1145c9d + 39fb692 commit abc3d74

File tree

250 files changed

+2514
-2682
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

250 files changed

+2514
-2682
lines changed

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ use Symfony\Contracts\Service\ServiceProviderInterface;
2222
use Symfony\UX\Toolkit\Command\DebugKitCommand;
2323
use Symfony\UX\Toolkit\Kit\KitSynchronizer;
2424
use Symfony\UX\Toolkit\Kit\KitFactory;
25+
use Symfony\UX\Toolkit\Recipe\RecipeSynchronizer;
2526
use Symfony\UX\Toolkit\Registry\GitHubRegistry;
2627
use Symfony\UX\Toolkit\Registry\LocalRegistry;
2728
use Symfony\UX\Toolkit\Registry\RegistryFactory;
@@ -46,7 +47,8 @@ if (!class_exists(Application::class)) {
4647
}
4748

4849
$filesystem = new Filesystem();
49-
$kitFactory = new KitFactory($filesystem, new KitSynchronizer($filesystem));
50+
$kitSynchronizer = new KitSynchronizer($filesystem, new RecipeSynchronizer($filesystem));
51+
$kitFactory = new KitFactory($filesystem, $kitSynchronizer);
5052

5153
(new Application())->add($command = new DebugKitCommand($kitFactory))
5254
->getApplication()

‎src/Toolkit/config/services.php

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,13 @@
1111

1212
namespace Symfony\Component\DependencyInjection\Loader\Configurator;
1313

14+
use Symfony\UX\Toolkit\Command\CreateKitCommand;
1415
use Symfony\UX\Toolkit\Command\DebugKitCommand;
15-
use Symfony\UX\Toolkit\Command\InstallComponentCommand;
16+
use Symfony\UX\Toolkit\Command\InstallCommand;
1617
use Symfony\UX\Toolkit\Kit\KitContextRunner;
1718
use Symfony\UX\Toolkit\Kit\KitFactory;
1819
use Symfony\UX\Toolkit\Kit\KitSynchronizer;
20+
use Symfony\UX\Toolkit\Recipe\RecipeSynchronizer;
1921
use Symfony\UX\Toolkit\Registry\GitHubRegistry;
2022
use Symfony\UX\Toolkit\Registry\LocalRegistry;
2123
use Symfony\UX\Toolkit\Registry\RegistryFactory;
@@ -34,7 +36,13 @@
3436
])
3537
->tag('console.command')
3638

37-
->set('.ux_toolkit.command.install', InstallComponentCommand::class)
39+
->set('.ux_toolkit.command.create_kit', CreateKitCommand::class)
40+
->args([
41+
service('filesystem'),
42+
])
43+
->tag('console.command')
44+
45+
->set('.ux_toolkit.command.install', InstallCommand::class)
3846
->args([
3947
service('.ux_toolkit.registry.registry_factory'),
4048
service('filesystem'),
@@ -75,6 +83,7 @@
7583
->set('.ux_toolkit.kit.kit_synchronizer', KitSynchronizer::class)
7684
->args([
7785
service('filesystem'),
86+
service('.ux_toolkit.recipe.recipe_synchronizer'),
7887
])
7988

8089
->set('ux_toolkit.kit.kit_context_runner', KitContextRunner::class)
@@ -83,5 +92,7 @@
8392
service('twig'),
8493
service('ux.twig_component.component_factory'),
8594
])
95+
96+
->set('.ux_toolkit.recipe.recipe_synchronizer', RecipeSynchronizer::class)
8697
;
8798
};

‎src/Toolkit/doc/index.rst

Lines changed: 63 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,24 @@ to change, or even change drastically.
77
Symfony UX Toolkit provides a set of ready-to-use kits for Symfony applications.
88
It is part of `the Symfony UX initiative`_.
99

10-
Kits are a nice way to begin a new Symfony application, by providing a set
11-
of `Twig components`_ (based on Tailwind CSS, but fully customizable depending
12-
on your needs).
10+
Kits are a nice way to begin a new Symfony application, they contains
11+
recipes to install nicely-crafter `Twig components`_ (already stylized,
12+
but fully customizable depending on your needs) and more.
1313

1414
Please note that the **UX Toolkit is not a library of UI components**,
1515
but **a tool to help you build your own UI components**.
1616
It uses the same approach than the popular `Shadcn UI`_,
1717
and a similar approach than `Tailwind Plus`_.
1818

19-
After installing the UX Toolkit, you can start pulling the components you need
20-
from `UX Toolkit Kits`_, and use them in your project.
21-
They become **your own components**, and **you can customize them as you want**.
19+
After installing the UX Toolkit, you can start installing the recipes you need
20+
from `UX Toolkit Kits`_ and use them in your project.
21+
Files created by the recipes become part of your project, and
22+
you can customize them as you want.
2223

2324
Additionally, some `Twig components`_ use ``html_cva`` and ``tailwind_merge``,
2425
you can either remove them from your project or install ``twig/html-extra``
2526
and ``tales-from-a-dev/twig-tailwind-extra`` to use them.
2627

27-
Also, we do not force you to use Tailwind CSS at all. You can use whatever
28-
CSS framework you want, but you will need to adapt the UI components to it.
29-
3028
Installation
3129
------------
3230

@@ -37,27 +35,25 @@ Install the UX Toolkit using Composer and Symfony Flex:
3735
# The UX Toolkit is a development dependency:
3836
$ composer require --dev symfony/ux-toolkit
3937
40-
# If you want to keep `html_cva` and `tailwind_merge` in your Twig components:
41-
$ composer require twig/extra-bundle twig/html-extra:^3.12.0 tales-from-a-dev/twig-tailwind-extra
42-
4338
Usage
4439
-----
4540

46-
You may find a list of components in the `UX Components page`_, with the installation instructions for each of them.
41+
You may find a list of available kits in the `UX Toolkit Kits`_ page, with the installation instructions for each of them.
4742

4843
For example, if you want to install a `Button` component, you will find the following instruction:
4944

5045
.. code-block:: terminal
5146
52-
$ php bin/console ux:toolkit:install-component Button --kit=<kitName>
47+
$ php bin/console ux:install Button --kit=<kitName>
5348
54-
It will create the ``templates/components/Button.html.twig`` file, and you will be able to use the `Button` component like this:
49+
It will create the ``templates/components/Button.html.twig`` file in your project,
50+
and you will be able to use the `Button` component like this:
5551

5652
.. code-block:: html+twig
5753

5854
<twig:Button>Click me</twig:Button>
5955

60-
Create your own kit
56+
Create your own Kit
6157
-------------------
6258

6359
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:
9692
.. code-block:: text
9793
9894
.
99-
├── docs
100-
│ └── components
101-
│ └── Button.twig
102-
├── manifest.json
103-
└── templates
104-
└── components
105-
└── Button.html.twig
106-
107-
A kit is composed of:
108-
109-
- A ``manifest.json`` file, that describes the kit (name, license, homepage, authors, ...),
110-
- A ``templates/components`` directory, that contains the Twig components,
111-
- A ``docs/components`` directory, optional, that contains the documentation for each "root" Twig component.
95+
├── Button
96+
│   ├── manifest.json
97+
│   └── templates
98+
│   └── components
99+
│   └── Button.html.twig
100+
└── manifest.json
101+
102+
103+
A kit is described by a ``manifest.json`` file at the root directory, which contains the metadata of the kit:
104+
105+
.. code-block:: json
106+
107+
{
108+
"$schema": "../vendor/symfony/ux-toolkit/schema-kit-v1.json",
109+
"name": "My UX Toolkit Kit",
110+
"description": "A custom kit for Symfony UX Toolkit.",
111+
"homepage": "https://github/com/User/MyUxToolkitKit",
112+
"license": "MIT"
113+
}
114+
115+
Then, a kit can contain one or more recipes. Each recipe is a directory
116+
with a ``manifest.json`` file and some files to be copied into the project.
117+
118+
The ``manifest.json`` file of a recipe contains the metadata of the recipe:
119+
120+
.. code-block:: json
121+
122+
{
123+
"$schema": "../vendor/symfony/ux-toolkit/schema-kit-recipe-v1.json",
124+
"name": "Button",
125+
"description": "A clickable element that triggers actions or events, supporting various styles and states.",
126+
"copy-files": {
127+
"templates/": "templates/"
128+
},
129+
"dependencies": {
130+
{
131+
"type": "php",
132+
"package": "twig/extra-bundle"
133+
},
134+
{
135+
"type": "php",
136+
"package": "twig/html-extra:^3.12.0"
137+
},
138+
{
139+
"type": "php",
140+
"package": "tales-from-a-dev/twig-tailwind-extra"
141+
}
142+
}
143+
}
112144
113145
Using your kit
114146
~~~~~~~~~~~~~~
@@ -117,10 +149,10 @@ Once your kit is published on GitHub, you can use it by specifying the ``--kit``
117149

118150
.. code-block:: terminal
119151
120-
$ php bin/console ux:toolkit:install-component Button --kit=github.com/my-username/my-ux-toolkit-kit
152+
$ php bin/console ux:install Button --kit=github.com/my-username/my-ux-toolkit-kit
121153
122154
# or for a specific version
123-
$ php bin/console ux:toolkit:install-component Button --kit=github.com/my-username/my-ux-toolkit-kit:1.0.0
155+
$ php bin/console ux:install Button --kit=github.com/my-username/my-ux-toolkit-kit:1.0.0
124156
125157
Backward Compatibility promise
126158
------------------------------

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

Lines changed: 3 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# Alert
1+
# Examples
22

3-
A notification component that displays important messages with an icon, title, and description.
3+
## Default
44

55
```twig {"preview":true}
66
<twig:Alert class="max-w-lg">
@@ -12,29 +12,7 @@ A notification component that displays important messages with an icon, title, a
1212
</twig:Alert>
1313
```
1414

15-
## Installation
16-
17-
<!-- Placeholder: Installation -->
18-
19-
## Usage
20-
21-
<!-- Placeholder: Usage -->
22-
23-
## Examples
24-
25-
### Default
26-
27-
```twig {"preview":true}
28-
<twig:Alert class="max-w-lg">
29-
<twig:ux:icon name="tabler:terminal" class="h-4 w-4" />
30-
<twig:Alert:Title>Heads up!</twig:Alert:Title>
31-
<twig:Alert:Description>
32-
You can add components to your app using the cli.
33-
</twig:Alert:Description>
34-
</twig:Alert>
35-
```
36-
37-
### Destructive
15+
## Destructive
3816

3917
```twig {"preview":true}
4018
<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

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
{
2-
"$schema": "../../../../schemas/component.json",
2+
"$schema": "../../../schema-kit-recipe-v1.json",
3+
"type": "component",
4+
"name": "Alert",
5+
"description": "A notification component that displays important messages with an icon, title, and description.",
6+
"copy-files": {
7+
"templates/": "templates/"
8+
},
39
"dependencies": [
410
{
511
"type": "php",

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

File renamed without changes.

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

File renamed without changes.

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

File renamed without changes.

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

Lines changed: 4 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
# AspectRatio
1+
# Examples
22

3-
A container that maintains a specific width-to-height ratio for its content.
3+
## Default
44

55
```twig {"preview":true,"height":"400px"}
66
<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.
1212
</twig:AspectRatio>
1313
```
1414

15-
## Installation
16-
17-
<!-- Placeholder: Installation -->
18-
19-
## Usage
20-
21-
<!-- Placeholder: Usage -->
22-
23-
## Examples
24-
25-
### With a 1 / 1 aspect ratio
15+
## With a 1 / 1 aspect ratio
2616

2717
```twig {"preview":true,"height":"400px"}
2818
<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.
3424
</twig:AspectRatio>
3525
```
3626

37-
### With a 16 / 9 aspect ratio
27+
## With a 16 / 9 aspect ratio
3828

3929
```twig {"preview":true,"height":"400px"}
4030
<twig:AspectRatio ratio="16 / 9" class="max-w-[350px]">

‎src/Toolkit/kits/shadcn/AspectRatio/manifest.json

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{
2+
"$schema": "../../../schema-kit-recipe-v1.json",
3+
"type": "component",
4+
"name": "AspectRatio",
5+
"description": "A container that maintains a specific width-to-height ratio for its content.",
6+
"copy-files": {
7+
"templates/": "templates/"
8+
},
9+
"dependencies": [
10+
{
11+
"type": "php",
12+
"package": "twig/extra-bundle"
13+
}
14+
]
15+
}

0 commit comments

Comments
 (0)