Make the development process easier 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,12 @@
+# 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.
+SIMPLE_HTTP_PORT=8000
+SIMPLE_HTTPS_PORT=4430
+SIMPLE_ENTRYPOINT=https://localhost:${SIMPLE_HTTPS_PORT}/api

.eslintrc.cjs

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

.gitignore

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

.storybook/main.ts

@@ -0,0 +1,33 @@
+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,
+    ENTRYPOINT: process.env.ENTRYPOINT ?? 'https://localhost/api',
+  }),
+  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

@@ -22,23 +22,25 @@ Then, if it appears that it's a real bug, you may report it using GitHub by foll
 
 ### Writing a Pull Request
 
-Please base your changes on the `master` branch.
+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.
 
-```shell
-yarn create react-app <yourproject>
-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.js` by this one:
+Your client should already uses `@api-platform/admin` and its bootstrap file (usually: `src/App.tsx`) should at least contains: 
 
-```javascript
+```tsx
 import React from 'react';
 import { HydraAdmin } from '@api-platform/admin';
 
@@ -86,7 +88,50 @@ cd ../<yourproject>/
 yarn start
 ```
 
-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
+```
 
 ### Testing Your Changes
 

Makefile

@@ -0,0 +1,18 @@
+include .env
+
+.PHONY        : help cp-env start-simple stop-simple
+
+help: ## Outputs this help screen
+	@grep -E '(^[a-zA-Z0-9\./_-]+:.*?##.*$$)|(^##)' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}{printf "\033[32m%-30s\033[0m %s\n", $$1, $$2}' | sed -e 's/\[32m##/[33m/'
+
+install: ## Install the dependencies
+	yarn install
+
+cp-env: ## Copy the .env file to .env.local
+	cp .env .env.local
+
+start-simple: ## Start the simple Api-Platform backend and the Storybook frontend
+	cd backend/simple && make build && make up HTTP_PORT=${SIMPLE_HTTP_PORT} HTTP3_PORT=${SIMPLE_HTTPS_PORT} HTTPS_PORT=${SIMPLE_HTTPS_PORT} && cd .. && yarn run storybook
+
+stop-simple: ## Stop and prune the simple Api-Platform backend
+	cd backend/simple && make prune

backend/simple/.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

backend/simple/.editorconfig

@@ -0,0 +1,58 @@
+# EditorConfig helps developers define and maintain consistent
+# coding styles between different editors and IDEs
+# editorconfig.org
+
+root = true
+
+[*]
+# Change these settings to your own preference
+indent_style = space
+indent_size = 4
+
+# We recommend you to keep these unchanged
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.{js,html,ts,tsx}]
+indent_size = 2
+
+[*.json]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.sh]
+indent_style = tab
+
+[*.xml{,.dist}]
+indent_style = space
+indent_size = 4
+
+[*.{yaml,yml}]
+trim_trailing_whitespace = false
+
+[.github/workflows/*.yml]
+indent_size = 2
+
+[.gitmodules]
+indent_style = tab
+
+[.php_cs{,.dist}]
+indent_style = space
+indent_size = 4
+
+[composer.json]
+indent_size = 4
+
+[{,docker-}compose{,.*}.{yaml,yml}]
+indent_style = space
+indent_size = 2
+
+[{,*.*}Dockerfile]
+indent_style = tab
+
+[{,*.*}Caddyfile]
+indent_style = tab

backend/simple/.env

@@ -0,0 +1,34 @@
+# 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
+
+###> symfony/framework-bundle ###
+APP_ENV=dev
+APP_SECRET=7aeabb40b0a766e29dec75f12f1e37c2
+###< 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:[email protected]: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 ###

backend/simple/.gitattributes

@@ -0,0 +1,17 @@
+* text=auto eol=lf
+
+*.conf text eol=lf
+*.html text eol=lf
+*.ini text eol=lf
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.php text eol=lf
+*.sh text eol=lf
+*.yaml text eol=lf
+*.yml text eol=lf
+bin/console text eol=lf
+composer.lock text eol=lf merge=ours
+
+*.ico binary
+*.png binary

backend/simple/.gitignore

@@ -0,0 +1,10 @@
+
+###> symfony/framework-bundle ###
+/.env.local
+/.env.local.php
+/.env.*.local
+/config/secrets/prod/prod.decrypt.private.php
+/public/bundles/
+/var/
+/vendor/
+###< symfony/framework-bundle ###