Interactive components in playground

.github/workflows/lint.yml

@@ -33,5 +33,7 @@ jobs:
           path: frontend/.yarn/cache
           key: ${{ runner.os }}-yarn-${{ hashFiles('frontend/yarn.lock') }}
           restore-keys: ${{ runner.os }}-yarn-
-      - run: yarn --cwd frontend
-      - run: make -C frontend lint
+      - run: yarn
+        working-directory: ./frontend
+      - run: make lint
+        working-directory: ./frontend

.github/workflows/release.yml

@@ -119,8 +119,10 @@ jobs:
       - uses: actions/setup-node@v2
         with:
           node-version: '16'
-      - run: yarn --cwd frontend
-      - run: make -C frontend build
+      - run: yarn
+        working-directory: ./frontend
+      - run: make build
+        working-directory: ./frontend
         env:
           # Don't convert warnings to errors, we love our warnings.
           CI: false

.github/workflows/test.yml

@@ -34,5 +34,7 @@ jobs:
           path: frontend/.yarn/cache
           key: ${{ runner.os }}-yarn-${{ hashFiles('frontend/yarn.lock') }}
           restore-keys: ${{ runner.os }}-yarn-
-      - run: yarn --cwd frontend
-      - run: make -C frontend test
+      - run: yarn
+        working-directory: ./frontend
+      - run: make test
+        working-directory: ./frontend

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## 1.4.0
 
+- Components of a user provided component library can now be used inside
+  `<Playground>` to create interactive demos of components.
 - Support _Table of Contents_ on documents.
 - Introduced new `<ImageGrid>` documentation component.
 

CONTRIBUTING.md

@@ -33,58 +33,49 @@ export PATH=$PATH:$(go env GOPATH)/bin
 
 ## Setup
 
-Clone the official repository, switch into the directory and checkout the branch
-you want to work on.
+First we'll be setting up an umbrella directory where the main dsk repository
+and supporting repositories will live, which we'll clone into it.
 
 ```
-$ git clone github.com/rundsk/dsk 
-$ git checkout 1.2
-$ cd dsk
-```
-
-When using the built-in frontend, the `frontend/build` folder must be
-present and contain the compiled version of the frontend. After a new
-checkout you can create it, using the following command. 
+mkdir rundsk
+cd rundsk
 
+git clone [email protected]:rundsk/dsk.git
+git clone [email protected]:rundsk/js-sdk.git
+git clone [email protected]:rundsk/example-component-library.git @rundsk/example-component-library
+git clone [email protected]:rundsk/example-design-system.git
 ```
-$ make -C frontend build
-```
-
-## Improving the frontend
 
-There are two ways to work on the built-in frontend and verify changes
-in your browser easily at the same time while you go.
+All the following documentation will assume that you are working from inside the
+main repository checkout.
 
-First start the backend which will also serve the frontend.
 ```
-$ make dev
+cd dsk
 ```
 
-Each time you change the source of the frontend run the following
-command and reload the browser window to see the changes.
+## Developing
 
-```
-$ make -C frontend build
-```
+First we'll start the backend in development mode and after that do the same
+with the frontend.
 
-Alternatively you can start the frontend (using a development server)
-and the backend separately on different ports, having the frontend use
-backend over its HTTP API.
+On a fresh checkout we'll have to install the dependencie of the frontend
+first, and then start the frontend's development server.
 
-Start the backend, first. By default it'll be reachable over port 8080.
 ```
-$ make dev
+cd frontend
+yarn
+make dev
 ```
 
-Second, start the frontend using a development server. It will be
-reachable over port 3000 and proxy requests through to the backend.
+You should now be able to reach the frontend when opening http://127.0.0.1:3000
+in your browser. You might see some errors as we not yet have started the backend.
+
+Now inside another terminal we'll start the backend.
 
 ```
-$ make -C frontend dev
+make dev
 ```
 
-Now open http://127.0.0.1:3000 in your browser.
-
 ## Debugging
 
 When running the tests the search indexes are store to disk, to ease

Makefile

@@ -6,6 +6,7 @@
 
 FRONTEND ?= $(shell pwd)/frontend/build
 DDT ?= $(shell pwd)/../example-design-system
+COMPONENTS ?= $(shell pwd)/../@rundsk/example-component-library
 
 VERSION ?= head-$(shell git rev-parse --short HEAD)
 LDFLAGS = -X main.Version=$(VERSION)
@@ -32,7 +33,7 @@ lint: internal/frontend/vfsdata.go
 .PHONY: dev
 dev: internal/frontend/vfsdata.go
 	go build -tags=dev -ldflags "$(LDFLAGS)" $(CMD_PKG)
-	./dsk -frontend $(FRONTEND) "$(DDT)"
+	./dsk -frontend $(FRONTEND) -components $(COMPONENTS) "$(DDT)"
 	rm dsk
 
 .PHONY: clean
@@ -45,7 +46,7 @@ clean:
 	if [ -f ./mem.prof ]; then rm ./mem.prof; fi
 
 .PHONY: dist
-dist: dist/dsk-darwin-amd64 dist/dsk-linux-amd64 dist/dsk-windows-386.exe 
+dist: dist/dsk-darwin-amd64 dist/dsk-linux-amd64 dist/dsk-windows-386.exe
 dist: dist/dsk-darwin-amd64.zip dist/dsk-linux-amd64.tar.gz dist/dsk-windows-386.zip
 dist: container-image
 	ls -lh dist
@@ -82,5 +83,5 @@ dist/%-linux-amd64: $(ANY_DEPS) internal/frontend/vfsdata.go
 dist/%-windows-386.exe: $(ANY_DEPS) internal/frontend/vfsdata.go
 	GOOS=windows GOARCH=386 go build -ldflags "$(LDFLAGS) -s -w" -o $@ $(CMD_PKG)
 
-internal/frontend/vfsdata.go: $(shell find $(FRONTEND) -type f) 
+internal/frontend/vfsdata.go: $(shell find $(FRONTEND) -type f)
 	FRONTEND=$(FRONTEND) go run cmd/frontend/generate.go

cmd/dsk/main.go

@@ -58,10 +58,11 @@ func main() {
 		}
 	}()
 
-	host := flag.String("host", "127.0.0.1", "host IP to bind to")
-	port := flag.String("port", "8080", "port to bind to")
-	version := flag.Bool("version", false, "print DSK version")
-	noColor := flag.Bool("no-color", false, "disables color output")
+	fhost := flag.String("host", "127.0.0.1", "host IP to bind to")
+	fport := flag.String("port", "8080", "port to bind to")
+	fversion := flag.Bool("version", false, "print DSK version")
+	fnoColor := flag.Bool("no-color", false, "disables color output")
+	fcomponents := flag.String("components", "", "path to component library assets")
 	ffrontend := flag.String("frontend", "", "path to a frontend, to use instead of the built-in")
 	fallowOrigin := flag.String("allow-origin", "", "origins from which browsers can access the HTTP API; for multiple origins, use a comma as a separator, the wildcard * is supported; to allow all use *")
 	flag.Parse()
@@ -70,14 +71,14 @@ func main() {
 		log.Fatalf("Too many arguments given, expecting exactly 0 or 1")
 	}
 
-	if *version {
+	if *fversion {
 		fmt.Println(Version)
 		os.Exit(1)
 	}
 
 	// Color package automatically disables colors when not a TTY. We
 	// don't need to check for an interactive terminal here again.
-	if *noColor {
+	if *fnoColor {
 		color.NoColor = true
 	}
 	whiteOnBlue := color.New(color.FgWhite, color.BgBlue)
@@ -114,7 +115,17 @@ func main() {
 	if err != nil {
 		panic(err)
 	}
-	log.Printf("Detected live path: %s", livePath)
+	log.Printf("Using live path: %s", livePath)
+
+	var componentsPath string
+	if *fcomponents != "" {
+		componentsPath = *fcomponents
+	}
+
+	var frontendPath string
+	if *ffrontend != "" {
+		frontendPath = *ffrontend
+	}
 
 	allowOrigins := strings.Split(*fallowOrigin, ",")
 	if len(allowOrigins) != 0 {
@@ -124,7 +135,8 @@ func main() {
 	app = plex.NewApp( // assign to global
 		Version,
 		livePath,
-		*ffrontend,
+		componentsPath,
+		frontendPath,
 	)
 	ctx, cancel := context.WithCancel(context.Background())
 	app.Teardown.AddCancelFunc(cancel)
@@ -133,6 +145,12 @@ func main() {
 		log.Fatal(red.Sprintf("Failed to initialize application: %s", err))
 	}
 
+	if componentsPath != "" {
+		if err := app.OpenComponents(ctx); err != nil {
+			log.Fatal(red.Sprintf("Failed to start application: %s", err))
+		}
+	}
+
 	if app.HasMultiVersionsSupport() {
 		log.Printf("Detected support for multi-versions")
 
@@ -145,7 +163,7 @@ func main() {
 
 	apis := map[int]httputil.Mountable{
 		1: api.NewV1(app.Sources, app.Version, app.Broker, allowOrigins),
-		2: api.NewV2(app.Sources, app.Version, app.Broker, allowOrigins),
+		2: api.NewV2(app.Sources, app.Components, app.Version, app.Broker, allowOrigins),
 	}
 	for av, a := range apis {
 		log.Printf("Mounting APIv%d HTTP mux...", av)
@@ -159,7 +177,7 @@ func main() {
 	log.Print("Mounting frontend HTTP mux...")
 	mux.Handle("/", app.Frontend.HTTPMux())
 
-	addr := fmt.Sprintf("%s:%s", *host, *port)
+	addr := fmt.Sprintf("%s:%s", *fhost, *fport)
 	if isTerminal {
 		log.Print("-------------------------------------------")
 		log.Printf("Please visit: %s", green.Sprint("http://"+addr))

frontend/.prettierrc

@@ -3,4 +3,5 @@
   "printWidth": 120,
   "bracketSpacing": true,
   "trailingComma": "es5",
+  "arrowParens": "always"
 }

frontend/.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+  "recommendations": [
+    "arcanis.vscode-zipfs",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode"
+  ]
+}

frontend/.vscode/settings.json

@@ -0,0 +1,8 @@
+{
+  "search.exclude": {
+    "**/.yarn": true,
+    "**/.pnp.*": true
+  },
+  "eslint.nodePath": ".yarn/sdks",
+  "prettier.prettierPath": ".yarn/sdks/prettier/index.js"
+}

frontend/.yarn/sdks/eslint/bin/eslint.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, createRequireFromPath} = require(`module`);
+const {resolve} = require(`path`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absRequire = (createRequire || createRequireFromPath)(absPnpApiPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require eslint/bin/eslint.js
+    require(absPnpApiPath).setup();
+  }
+}
+
+// Defer to the real eslint/bin/eslint.js your application uses
+module.exports = absRequire(`eslint/bin/eslint.js`);

frontend/.yarn/sdks/eslint/lib/api.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, createRequireFromPath} = require(`module`);
+const {resolve} = require(`path`);
+
+const relPnpApiPath = "../../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absRequire = (createRequire || createRequireFromPath)(absPnpApiPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require eslint/lib/api.js
+    require(absPnpApiPath).setup();
+  }
+}
+
+// Defer to the real eslint/lib/api.js your application uses
+module.exports = absRequire(`eslint/lib/api.js`);

frontend/.yarn/sdks/eslint/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "eslint",
+  "version": "7.32.0-sdk",
+  "main": "./lib/api.js",
+  "type": "commonjs"
+}

frontend/.yarn/sdks/integrations.yml

@@ -0,0 +1,5 @@
+# This file is automatically generated by @yarnpkg/sdks.
+# Manual changes might be lost!
+
+integrations:
+  - vscode

frontend/.yarn/sdks/prettier/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const {existsSync} = require(`fs`);
+const {createRequire, createRequireFromPath} = require(`module`);
+const {resolve} = require(`path`);
+
+const relPnpApiPath = "../../../.pnp.cjs";
+
+const absPnpApiPath = resolve(__dirname, relPnpApiPath);
+const absRequire = (createRequire || createRequireFromPath)(absPnpApiPath);
+
+if (existsSync(absPnpApiPath)) {
+  if (!process.versions.pnp) {
+    // Setup the environment to be able to require prettier/index.js
+    require(absPnpApiPath).setup();
+  }
+}
+
+// Defer to the real prettier/index.js your application uses
+module.exports = absRequire(`prettier/index.js`);

frontend/.yarn/sdks/prettier/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "prettier",
+  "version": "2.4.1-sdk",
+  "main": "./index.js",
+  "type": "commonjs"
+}

frontend/Makefile

@@ -10,7 +10,7 @@ dev:
 
 .PHONY: test
 test:
-	yarn react-scripts test .
+	yarn test
 
 .PHONY: build
 build:
@@ -26,7 +26,7 @@ lint:
 .PHONY: format
 format:
 	yarn eslint --fix --cache src
-	yarn prettier --write src/**
+	yarn prettier --write 'src/**/*.{js,jsx,css,scss,json}'
 
 .PHONY: clean
 clean: