[Toolkit] Refactor ToolkitKit enum to ToolkitKitId, leverage description/uxIcon/installation steps in Kit VO

Author: Kocal

src/Toolkit/kits/shadcn/INSTALL.md

@@ -0,0 +1,102 @@
+# Getting started
+
+This kit provides ready-to-use and fully-customizable UI Twig components based on [Shadcn UI](https://ui.shadcn.com/) components's **design**.
+
+Please note that not every Shadcn UI component is available in this kit, but we are working on it!
+
+## Requirements
+
+This kit requires TailwindCSS to work:
+- If you use Symfony AssetMapper, you can install TailwindCSS with the [TailwindBundle](https://symfony.com/bundles/TailwindBundle/current/index.html),
+- If you use Webpack Encore, you can follow the [TailwindCSS installation guide for Symfony](https://tailwindcss.com/docs/installation/framework-guides/symfony)
+
+## Installation
+
+In your `assets/styles/app.css`, after the TailwindCSS imports, add the following code:
+
+```css
+@custom-variant dark (&:is(.dark *));
+
+:root {
+    --radius: 0.625rem;
+    --background: oklch(1 0 0);
+    --foreground: oklch(0.145 0 0);
+    --card: oklch(1 0 0);
+    --card-foreground: oklch(0.145 0 0);
+    --popover: oklch(1 0 0);
+    --popover-foreground: oklch(0.145 0 0);
+    --primary: oklch(0.205 0 0);
+    --primary-foreground: oklch(0.985 0 0);
+    --secondary: oklch(0.97 0 0);
+    --secondary-foreground: oklch(0.205 0 0);
+    --muted: oklch(0.97 0 0);
+    --muted-foreground: oklch(0.556 0 0);
+    --accent: oklch(0.97 0 0);
+    --accent-foreground: oklch(0.205 0 0);
+    --destructive: oklch(0.577 0.245 27.325);
+    --border: oklch(0.922 0 0);
+    --input: oklch(0.922 0 0);
+    --ring: oklch(0.708 0 0);
+    --chart-1: oklch(0.646 0.222 41.116);
+    --chart-2: oklch(0.6 0.118 184.704);
+    --chart-3: oklch(0.398 0.07 227.392);
+    --chart-4: oklch(0.828 0.189 84.429);
+    --chart-5: oklch(0.769 0.188 70.08);
+    --sidebar: oklch(0.985 0 0);
+    --sidebar-foreground: oklch(0.145 0 0);
+    --sidebar-primary: oklch(0.205 0 0);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.97 0 0);
+    --sidebar-accent-foreground: oklch(0.205 0 0);
+    --sidebar-border: oklch(0.922 0 0);
+    --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+    --background: oklch(0.145 0 0);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.205 0 0);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.269 0 0);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.922 0 0);
+    --primary-foreground: oklch(0.205 0 0);
+    --secondary: oklch(0.269 0 0);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.269 0 0);
+    --muted-foreground: oklch(0.708 0 0);
+    --accent: oklch(0.371 0 0);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.556 0 0);
+    --chart-1: oklch(0.488 0.243 264.376);
+    --chart-2: oklch(0.696 0.17 162.48);
+    --chart-3: oklch(0.769 0.188 70.08);
+    --chart-4: oklch(0.627 0.265 303.9);
+    --chart-5: oklch(0.645 0.246 16.439);
+    --sidebar: oklch(0.205 0 0);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.269 0 0);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.439 0 0);
+}
+
+@layer base {
+    * {
+        border-color: var(--border);
+        outline-color: var(--ring);
+    }
+
+    body {
+        background-color: var(--background);
+        color: var(--foreground);
+    }
+}
+```
+
+And voilà! You are now ready to use Shadcn components in your Symfony project.

src/Toolkit/kits/shadcn/manifest.json

@@ -1,6 +1,8 @@
 {
-    "name": "Shadcn",
+    "name": "Shadcn UI",
+    "description": "Component based on the Shadcn UI library, one of the most popular design systems in JavaScript world.",
     "license": "MIT",
     "homepage": "https://ux.symfony.com/components",
-    "authors": ["Shadcn", "Symfony Community"]
+    "authors": ["Shadcn", "Symfony Community"],
+    "ux-icon": "simple-icons:shadcnui"
 }

src/Toolkit/src/Assert.php

@@ -22,7 +22,7 @@
      */
     public static function kitName(string $name): void
     {
-        if (1 !== preg_match('/^[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?$/', $name)) {
+        if (1 !== preg_match('/^[a-zA-Z0-9](?:[a-zA-Z0-9-_ ]{0,61}[a-zA-Z0-9])?$/', $name)) {
             throw new \InvalidArgumentException(\sprintf('Invalid kit name "%s".', $name));
         }
     }

src/Toolkit/src/Kit/Kit.php

@@ -36,6 +36,9 @@ public function __construct(
         public readonly string $homepage,
         public readonly array $authors,
         public readonly string $license,
+        public readonly ?string $description = null,
+        public readonly ?string $uxIcon = null,
+        public ?string $installAsMarkdown = null,
         private array $components = [],
     ) {
         Assert::kitName($this->name);

src/Toolkit/src/Kit/KitFactory.php

@@ -54,11 +54,13 @@ public function createKitFromAbsolutePath(string $absolutePath): Kit
         $manifest = json_decode($this->filesystem->readFile($manifestPath), true, flags: \JSON_THROW_ON_ERROR);
 
         $kit = new Kit(
-            $absolutePath,
-            $manifest['name'] ?? throw new \InvalidArgumentException('Manifest file is missing "name" key.'),
-            $manifest['homepage'] ?? throw new \InvalidArgumentException('Manifest file is missing "homepage" key.'),
-            $manifest['authors'] ?? throw new \InvalidArgumentException('Manifest file is missing "authors" key.'),
-            $manifest['license'] ?? throw new \InvalidArgumentException('Manifest file is missing "license" key.'),
+            path: $absolutePath,
+            name: $manifest['name'] ?? throw new \InvalidArgumentException('Manifest file is missing "name" key.'),
+            homepage: $manifest['homepage'] ?? throw new \InvalidArgumentException('Manifest file is missing "homepage" key.'),
+            authors: $manifest['authors'] ?? throw new \InvalidArgumentException('Manifest file is missing "authors" key.'),
+            license: $manifest['license'] ?? throw new \InvalidArgumentException('Manifest file is missing "license" key.'),
+            description: $manifest['description'] ?? null,
+            uxIcon: $manifest['ux-icon'] ?? null,
         );
 
         $this->synchronizeKit($kit);
@@ -69,6 +71,7 @@ public function createKitFromAbsolutePath(string $absolutePath): Kit
     private function synchronizeKit(Kit $kit): void
     {
         $this->synchronizeKitComponents($kit);
+        $this->synchronizeKitDocumentation($kit);
     }
 
     private function synchronizeKitComponents(Kit $kit): void
@@ -86,15 +89,13 @@ private function synchronizeKitComponents(Kit $kit): void
             $relativePathNameToKit = $file->getRelativePathname();
             $relativePathName = str_replace($componentsPath.\DIRECTORY_SEPARATOR, '', $relativePathNameToKit);
             $componentName = $this->extractComponentName($relativePathName);
-            $docPath = Path::join($kit->path, 'docs', 'components', $componentName.'.md');
             $component = new Component(
                 name: $componentName,
                 files: [new File(
                     type: FileType::Twig,
                     relativePathNameToKit: $relativePathNameToKit,
                     relativePathName: $relativePathName,
                 )],
-                doc: $this->filesystem->exists($docPath) ? new Doc($this->filesystem->readFile($docPath)) : null,
             );
 
             $kit->addComponent($component);
@@ -107,4 +108,21 @@ private static function extractComponentName(string $pathnameRelativeToKit): str
     {
         return str_replace(['.html.twig', '/'], ['', ':'], $pathnameRelativeToKit);
     }
+
+    private function synchronizeKitDocumentation(Kit $kit): void
+    {
+        // Read INSTALL.md if exists
+        $fileInstall = Path::join($kit->path, 'INSTALL.md');
+        if ($this->filesystem->exists($fileInstall)) {
+            $kit->installAsMarkdown = $this->filesystem->readFile($fileInstall);
+        }
+
+        // Iterate over Component and find their documentation
+        foreach ($kit->getComponents() as $component) {
+            $docPath = Path::join($kit->path, 'docs', 'components', $component->name.'.md');
+            if ($this->filesystem->exists($docPath)) {
+                $component->doc = new Doc($this->filesystem->readFile($docPath));
+            }
+        }
+    }
 }

src/Toolkit/tests/AssertTest.php

@@ -33,8 +33,8 @@ public static function provideValidKitNames(): \Generator
         yield ['1-my-kit'];
         yield ['my-kit-1'];
         yield ['my-kit-1-with-dashes'];
-        yield ['Shadcn-UI'];
-        yield ['Shadcn-UI-1'];
+        yield ['Shadcn UI'];
+        yield ['Shadcn UI-1'];
         // Single character
         yield ['a'];
         yield ['1'];
@@ -47,6 +47,7 @@ public static function provideValidKitNames(): \Generator
         yield ['a-b-c'];
         yield ['a1-b2-c3'];
         yield ['A1-B2-C3'];
+        yield ['my_kit'];
     }
 
     /**
@@ -71,7 +72,6 @@ public static function provideInvalidKitNames(): \Generator
         // Ending with hyphen
         yield ['my-kit-'];
         // Invalid characters
-        yield ['my_kit'];
         yield ['my.kit'];
         yield ['my@kit'];
         // Too long (64 chars)

src/Toolkit/tests/Command/LintKitCommandTest.php

@@ -24,7 +24,7 @@ public function testShouldBeAbleToLint(): void
         $this->consoleCommand('ux:toolkit:lint-kit shadcn')
             ->execute()
             ->assertSuccessful()
-            ->assertOutputContains('The kit "Shadcn" is valid, it has 46 components')
+            ->assertOutputContains('The kit "Shadcn UI" is valid, it has 46 components')
         ;
     }
 }

src/Toolkit/tests/Kit/KitFactoryTest.php

@@ -14,7 +14,6 @@
 use Symfony\Bundle\FrameworkBundle\Test\KernelTestCase;
 use Symfony\UX\Toolkit\Dependency\ComponentDependency;
 use Symfony\UX\Toolkit\Dependency\PhpPackageDependency;
-use Symfony\UX\Toolkit\Dependency\Version;
 use Symfony\UX\Toolkit\Kit\KitFactory;
 
 final class KitFactoryTest extends KernelTestCase

src/Toolkit/tests/Registry/GitHubRegistryTest.php

@@ -64,7 +64,7 @@ public function testCanGetKitFromGithub(): void
         $kit = $githubRegistry->getKit('github.com/user/repo');
 
         $this->assertTrue($isHttpClientCalled);
-        $this->assertSame('Shadcn', $kit->name);
+        $this->assertSame('Shadcn UI', $kit->name);
         $this->assertNotEmpty($kit->getComponents());
         $this->assertFileExists($kit->path);
         $this->assertFileExists(Path::join($kit->path, 'templates/components/Button.html.twig'));

src/Toolkit/tests/Registry/LocalRegistryTest.php

@@ -28,6 +28,6 @@ public function testCanGetKit(): void
         $kit = $localRegistry->getKit('shadcn');
 
         $this->assertInstanceOf(Kit::class, $kit);
-        $this->assertSame('Shadcn', $kit->name);
+        $this->assertSame('Shadcn UI', $kit->name);
     }
 }