chore: add a way to developp with Storybook

.babelrc.json

@@ -0,0 +1,18 @@
+{
+  "sourceType": "unambiguous",
+  "presets": [
+    [
+      "@babel/preset-env",
+      {
+        "targets": {
+          "chrome": 100,
+          "safari": 15,
+          "firefox": 91
+        }
+      }
+    ],
+    "@babel/preset-typescript",
+    "@babel/preset-react"
+  ],
+  "plugins": []
+}

.env

@@ -0,0 +1,9 @@
+# In all environments, the following files are loaded if they exist,
+# the latter taking precedence over the former:
+#
+#  * .env                contains default values for the environment variables needed by the app
+#  * .env.local          uncommitted file with local overrides
+#
+# Real environment variables win over .env files.
+#
+# DO NOT DEFINE PRODUCTION SECRETS IN THIS FILE NOR IN ANY OTHER COMMITTED FILES.

.eslintrc.cjs

@@ -7,6 +7,7 @@ module.exports = {
     'airbnb/hooks',
     'prettier',
     'plugin:markdown/recommended',
+    'plugin:storybook/recommended'
   ],
   rules: {
     'prettier/prettier': 'error',

.gitignore

@@ -1,2 +1,5 @@
 /lib/
 node_modules/
+/yarn.lock
+.vscode/
+.env.local

.storybook/main.ts

@@ -0,0 +1,32 @@
+import type { StorybookConfig } from '@storybook/react-webpack5';
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    '@storybook/addon-onboarding',
+    '@storybook/addon-interactions',
+  ],
+  framework: {
+    name: '@storybook/react-webpack5',
+    options: {},
+  },
+  docs: {
+    autodocs: 'tag',
+  },
+  env: (config) => ({
+    ...config,
+  }),
+  async webpackFinal(config, { configType }) {
+    config.resolve = {
+      ...config.resolve,
+      extensionAlias: {
+        '.js': ['.ts', '.js', '.tsx'],
+      },
+    };
+    return config;
+  },
+};
+
+export default config;

.storybook/preview.ts

@@ -0,0 +1,15 @@
+import type { Preview } from '@storybook/react';
+
+const preview: Preview = {
+  parameters: {
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

CONTRIBUTING.md

@@ -24,21 +24,24 @@ Then, if it appears that it's a real bug, you may report it using GitHub by foll
 
 Please base your changes on the `main` branch.
 
-### Installing the Source Version
+### Two ways to write your patch
 
-To install the source version of API Platform Admin in your project and contribute a patch, follow the instructions below.
+You can patch `@api-platform/admin` by two different ways:
+- by linking `@api-platform/admin` sources to an existing project;
+- by installing this project and running it through Storybook.
 
-Create your client that will use `@api-platform/admin` (replace `<yourproject>` by your project's name):
+> Prerequiste: running Api-Platform backend. See the [Getting Started guide](https://api-platform.com/docs/distribution/) to learn more.
 
-```console
-yarn create vite <yourproject> --template react-ts
-cd <yourproject>
-yarn add @api-platform/admin
-```
+#### Linking the Source Version to an existing project
+
+If you already have a project in progress, you can develop directly from it.
+
+The instructions below explain how to install the source version of API Platform Admin in your project and contribute a patch.
 
-Replace `src/App.tsx` by this one:
+Your client should already uses `@api-platform/admin` and its bootstrap file (usually: `src/App.tsx`) should at least contains: 
 
-```typescript
+```tsx
+import React from 'react';
 import { HydraAdmin } from '@api-platform/admin';
 
 function App() {
@@ -92,7 +95,50 @@ yarn install --force
 yarn dev --force
 ```
 
-You can now hack in the cloned repository of `api-platform-admin`.
+> You can now hack in the cloned repository of `api-platform-admin`.
+
+#### Running Admin through Storybook
+
+If you don't have an existing API Platform application, you can use one of the bundled example APIs, and visualize the admin through [Storybook](https://storybook.js.org/).
+
+Get the source of `@api-platform/admin`:
+
+```shell
+cd ..
+git clone https://github.com/api-platform/admin.git
+```
+
+Install everything:
+
+```shell
+cd admin
+# Install JS dependencies
+make install
+# (optional) Initizalize a .env containing the URL of the API 
+make cp-env
+```
+
+The default API URL is in the `.env`. You can customize it according to your needs:
+
+```env
+SIMPLE_HTTP_PORT=8000
+SIMPLE_HTTPS_PORT=4430
+SIMPLE_ENTRYPOINT=https://localhost:${SIMPLE_HTTPS_PORT}/api
+```
+
+Run the simple API Platform backend (uses docker) and launch Storybook:
+
+```shell
+make start-simple
+```
+
+Go to http://localhost:4430, accept the self-signed certificate, visit http://localhost:6006 to see the running Admin.
+
+To stop and prune the simple API Platform backend:
+
+```shell
+make stop-simple
+```
 
 Each time you change your code, you must restart vite with `--force` option [for your changes to be taken into account](https://vitejs.dev/guide/troubleshooting.html#outdated-pre-bundled-deps-when-linking-to-a-local-package
 ):

Dockerfile

@@ -0,0 +1,28 @@
+#syntax=docker/dockerfile:1.4
+
+
+# Versions
+FROM node:20-alpine AS node_upstream
+
+
+# Base stage for dev and build
+FROM node_upstream AS base
+
+# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
+# hadolint ignore=DL3018
+RUN apk add --no-cache libc6-compat
+
+WORKDIR /srv/app
+
+RUN corepack enable && \
+	corepack prepare --activate pnpm@latest && \
+	pnpm config -g set store-dir /.pnpm-store
+
+# Development image
+FROM base as dev
+
+EXPOSE 3000
+ENV PORT 3000
+ENV HOSTNAME localhost
+
+CMD ["sh", "-c", "pnpm install; pnpm storybook"]

api/.dockerignore

@@ -0,0 +1,34 @@
+**/*.log
+**/*.md
+**/*.php~
+**/*.dist.php
+**/*.dist
+**/*.cache
+**/._*
+**/.dockerignore
+**/.DS_Store
+**/.git/
+**/.gitattributes
+**/.gitignore
+**/.gitmodules
+**/compose.*.yaml
+**/compose.*.yml
+**/compose.yaml
+**/compose.yml
+**/docker-compose.*.yaml
+**/docker-compose.*.yml
+**/docker-compose.yaml
+**/docker-compose.yml
+**/Dockerfile
+**/Thumbs.db
+.github/
+docs/
+public/bundles/
+tests/
+var/
+vendor/
+.editorconfig
+.env.*.local
+.env.local
+.env.local.php
+.env.test

api/.env

@@ -0,0 +1,48 @@
+# In all environments, the following files are loaded if they exist,
+# the latter taking precedence over the former:
+#
+#  * .env                contains default values for the environment variables needed by the app
+#  * .env.local          uncommitted file with local overrides
+#  * .env.$APP_ENV       committed environment-specific defaults
+#  * .env.$APP_ENV.local uncommitted environment-specific overrides
+#
+# Real environment variables win over .env files.
+#
+# DO NOT DEFINE PRODUCTION SECRETS IN THIS FILE NOR IN ANY OTHER COMMITTED FILES.
+# https://symfony.com/doc/current/configuration/secrets.html
+#
+# Run "composer dump-env prod" to compile .env files for production use (requires symfony/flex >=1.2).
+# https://symfony.com/doc/current/best_practices.html#use-environment-variables-for-infrastructure-configuration
+
+# API Platform distribution
+TRUSTED_PROXIES=127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16
+TRUSTED_HOSTS=^(localhost|php)$
+
+###> symfony/framework-bundle ###
+APP_ENV=dev
+APP_SECRET=!ChangeMe!
+###< symfony/framework-bundle ###
+
+###> doctrine/doctrine-bundle ###
+# Format described at https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
+# IMPORTANT: You MUST configure your server version, either here or in config/packages/doctrine.yaml
+#
+# DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db"
+# DATABASE_URL="mysql://app:[email protected]:3306/app?serverVersion=8.0.32&charset=utf8mb4"
+# DATABASE_URL="mysql://app:[email protected]:3306/app?serverVersion=10.11.2-MariaDB&charset=utf8mb4"
+DATABASE_URL="postgresql://app:!ChangeMe!@database:5432/app?serverVersion=15&charset=utf8"
+###< doctrine/doctrine-bundle ###
+
+###> nelmio/cors-bundle ###
+CORS_ALLOW_ORIGIN='^https?://(localhost|127\.0\.0\.1)(:[0-9]+)?$'
+###< nelmio/cors-bundle ###
+
+###> symfony/mercure-bundle ###
+# See https://symfony.com/doc/current/mercure.html#configuration
+# The URL of the Mercure hub, used by the app to publish updates (can be a local URL)
+MERCURE_URL=http://php/.well-known/mercure
+# The public URL of the Mercure hub, used by the browser to connect
+MERCURE_PUBLIC_URL=https://localhost/.well-known/mercure
+# The secret used to sign the JWTs
+MERCURE_JWT_SECRET="!ChangeThisMercureHubJWTSecretKey!"
+###< symfony/mercure-bundle ###

api/.env.test

@@ -0,0 +1,9 @@
+# define your env variables for the test env here
+KERNEL_CLASS='App\Kernel'
+APP_SECRET='$ecretf0rt3st'
+SYMFONY_DEPRECATIONS_HELPER=999999
+PANTHER_APP_ENV=panther
+PANTHER_ERROR_SCREENSHOT_DIR=./var/error-screenshots
+
+# API Platform distribution
+TRUSTED_HOSTS=^example\.com|localhost$

api/.gitignore

@@ -0,0 +1,21 @@
+/docker/db/data
+
+###> symfony/framework-bundle ###
+/.env.local
+/.env.local.php
+/.env.*.local
+/config/secrets/prod/prod.decrypt.private.php
+/public/bundles/
+/var/
+/vendor/
+###< symfony/framework-bundle ###
+
+###> friendsofphp/php-cs-fixer ###
+/.php-cs-fixer.php
+/.php-cs-fixer.cache
+###< friendsofphp/php-cs-fixer ###
+
+###> symfony/phpunit-bridge ###
+.phpunit.result.cache
+/phpunit.xml
+###< symfony/phpunit-bridge ###

api/.php-cs-fixer.dist.php

@@ -0,0 +1,13 @@
+<?php
+
+$finder = (new PhpCsFixer\Finder())
+    ->in(__DIR__)
+    ->exclude('var')
+;
+
+return (new PhpCsFixer\Config())
+    ->setRules([
+        '@Symfony' => true,
+    ])
+    ->setFinder($finder)
+;