docs: add flag definition playground (#1084)

Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com>
Signed-off-by: Todd Baert <todd.baert@dynatrace.com>
Co-authored-by: Todd Baert <todd.baert@dynatrace.com>

Author: beeme1mr

.gitignore

@@ -12,6 +12,7 @@ core-coverage.out
 go.work
 go.work.sum
 bin/
+node_modules/
 
 # built documentation
 site

.markdownlint-cli2.yaml

@@ -16,9 +16,12 @@ config:
 
 ignores:
   - "**/CHANGELOG.md"
+  - ".venv"
   - "node_modules"
+  - "playground-app/node_modules"
   - "tmp"
-  - "**/protos.md"  # auto-generated
-  - "schemas"       # submodule
-  - "spec"          # submodule
-  - "test-harness"  # submodule
+  - "**/protos.md"     # auto-generated
+  - "docs/playground"  # auto-generated
+  - "schemas"          # submodule
+  - "spec"             # submodule
+  - "test-harness"     # submodule

.nvmrc

@@ -0,0 +1 @@
+v18

Makefile

@@ -123,4 +123,22 @@ generate-proto-docs: pull-schemas-submodule
 
 .PHONY: run-web-docs
 run-web-docs: generate-docs generate-proto-docs
-	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+	docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material
+
+# Run the playground app in dev mode
+# See the readme in the playground-app folder for more details
+.PHONY: playground-dev
+playground-dev:
+	cd playground-app && npm ci && npm run dev
+
+# Build the playground app
+# See the readme in the playground-app folder for more details
+.PHONY: playground-build
+playground-build:
+	cd playground-app && npm ci && npm run build
+
+# Publish the playground app to the docs folder
+# See the readme in the playground-app folder for more details
+.PHONY: playground-publish
+playground-publish: playground-build
+	cp playground-app/dist/assets/index-*.js docs/playground/playground.js

docs/assets/extra.css

@@ -17,4 +17,17 @@
   --md-default-bg-color--light:      hsla(240, 4%, 11%, 0.54);
   --md-default-bg-color--lighter:    hsla(240, 4%, 11%, 0.26);
   --md-default-bg-color--lightest:   hsla(240, 4%, 11%, 0.07);
+}
+button:disabled {
+  opacity: 0.5;
+  cursor: not-allowed !important;
+}
+
+.output {
+  transition: opacity .5s ease-in-out;
+  opacity: 0;
+}
+
+.output.visible {
+  opacity: 1;
 }

docs/playground/index.md

@@ -0,0 +1,6 @@
+<!--
+The playground.js is automatically generated using the 'make playground-publish' command.
+For more information, please refer to the README.md in 'playground-app' folder.
+-->
+<script type="module" crossorigin src="./playground.js"></script>
+<div id="playground"></div>

docs/playground/playground.js

@@ -18,7 +18,7 @@ theme:
       primary: custom
       accent: custom
       toggle:
-        icon: material/toggle-switch-off      
+        icon: material/toggle-switch-off
         name: Switch to light mode
   logo: assets/logo-white.svg
   favicon: assets/logo-white.svg
@@ -55,6 +55,7 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   - tables
   - attr_list
+  - md_in_html
   - pymdownx.emoji:
       # we are using an older emoji extension because the newest (suggested in docs) doesn't work with Python < 3.10
       emoji_index: !!python/name:materialx.emoji.twemoji
@@ -64,6 +65,7 @@ nav:
   - 'Introduction': 'index.md'
   - 'Quick start': 'quick-start.md'
   - 'Installation': 'installation.md'
+  - 'Playground': 'playground/index.md'
   - 'Concepts':
     - 'Feature Flagging': 'concepts/feature-flagging.md'
     - 'Syncs': 'concepts/syncs.md'

mkdocs.yml

@@ -0,0 +1,18 @@
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  ignorePatterns: ['dist', '.eslintrc.cjs'],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}

playground-app/.eslintrc.cjs

@@ -0,0 +1,40 @@
+# flagd playground
+
+The flagd playground is an application designed to test the behavior of flagd.
+It allows users to define flags and experiment with various inputs to understand how flagd responds.
+This tool is particularly useful for developers and testers who are working with flagd in their projects and need a simple and effective way to validate their flag definitions.
+
+## Development
+
+### Getting Started
+
+To get started with the development of the flagd playground, you'll need to have Node.js installed on your machine.
+
+1. Install [Node.js](https://nodejs.org/en/download/) version 18 or newer.
+1. From the root of the project, run `make playground-dev`.
+1. Open your browser and navigate to [http://localhost:5173/](http://localhost:5173/);
+
+> [!NOTE]
+> This page is mostly unstyled because it inherits the styles from Mkdocs Material.
+
+### Add a new scenario
+
+A new scenario can be added to the playground by following these steps:
+
+1. Add a new scenario file during the ``./src/scenarios`` directory.
+1. Export a constant that conforms to the `Scenario` type.
+1. Include the scenario in the scenarios objects at `./src/scenarios/index.ts`.
+
+> [!NOTE]
+> Make sure to update the docs once you're ready. This does not happen automatically! Please see below for more information.
+
+### Adding Playground to the Docs
+
+Adding the playground app to the docs can be done by running the following command from the root of the project:
+
+```bash
+make make playground-publish
+```
+
+> [!NOTE]
+> This will build the app and copy the output to the docs.

playground-app/README.md

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+</head>
+
+<body>
+  <div id="playground"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+
+</html>