WIP: Interactive Playgrounds

- Support the `-components` flag on `dsk`, to allow passing
  a path to a pre-build component bundle output directory.
- Provide playground handlers.
- Refactor `<Playground>`
- Use IFrame in Playground

Unrelated:

- Deprecate Node.components response property.
- Improve routing techniques, by using sub routers and allow
  us to extract route params.
- Rename flag variables.
- Pass more parent and current node into documentation components.
- Nodes now have an `id` that can be used to adress them. Although not
  from the outside.

Author: mariuswilms

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

@@ -20,7 +20,7 @@ the `frontend/build` directory by default.
 
 ## Prerequisites
 
-[Go](https://golang.org/) version 1.11 or later is needed for developing
+[Go](https://golang.org/) version 1.16 or later is needed for developing
 and testing the application. [Node.js](https://nodejs.org) and
 [Yarn](https://yarnpkg.com) are needed to build the built-in frontend.
 
@@ -31,67 +31,51 @@ directory to your `PATH`, so that go binaries can be found. In
 export PATH=$PATH:$(go env GOPATH)/bin
 ```
 
-DSK uses `go mod` to manage its dependencies. When using
-Go 1.11 module support must be explictly enabled, add this line to
-`.profile`:
-```
-export GO111MODULE=on
-```
-
 ## 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
-```
+mkdir rundsk
+cd rundsk
 
-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. 
-
-```
-$ make -C frontend build
+git clone git@github.com:rundsk/dsk.git
+git clone git@github.com:rundsk/js-sdk.git
+git clone git@github.com:rundsk/example-component-library.git
+git clone git@github.com:rundsk/example-design-system.git
 ```
 
-## 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)/../example-component-library/build
 
 VERSION ?= head-$(shell git rev-parse --short HEAD)
 LDFLAGS = -X main.Version=$(VERSION)
@@ -32,7 +33,7 @@ lint:
 .PHONY: dev
 dev:
 	go build -tags=dev -ldflags "$(LDFLAGS)" $(CMD_PKG)
-	./dsk -frontend $(FRONTEND) "$(DDT)"
+	./dsk -frontend $(FRONTEND) -components $(COMPONENTS) "$(DDT)"
 	rm dsk
 
 .PHONY: clean

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.Print(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/src/Breadcrumbs/index.js

@@ -14,7 +14,7 @@ function Breadcrumbs(props) {
   let crumbs;
 
   if (props.crumbs) {
-    crumbs = props.crumbs.map(c => {
+    crumbs = props.crumbs.map((c) => {
       return (
         <li className="breadcrumbs__crumb" key={c.title}>
           <BaseLink
@@ -25,7 +25,6 @@ function Breadcrumbs(props) {
           >
             {c.title}
           </BaseLink>
-          {/* <a href={`/tree/${c.url}`}>{c.title}</a> */}
         </li>
       );
     });

frontend/src/CodeBlock/index.js

@@ -59,7 +59,7 @@ function CodeBlock(props) {
 
   useEffect(() => {
     if (props.src) {
-      Client.fetch(props.src, 'text').then(data => setCode(<code className="code-block__code-content">{data}</code>));
+      Client.fetch(props.src, 'text').then((data) => setCode(<code className="code-block__code-content">{data}</code>));
     } else {
       let content;
 

frontend/src/Doc/index.js

@@ -46,47 +46,51 @@ function Doc(props) {
     return <div className="doc">{props.children}</div>;
   }
 
-  // Allow to use this inside the `transforms` constant. We cannot use
-  // `props.title` there as that refers to the component/element that is being
-  // transformed. The title is needed as to calculate the `Heading`'s jump
-  // anchor.
-  let docTitle = props.title;
+  // Transform context: Allow to use this inside the `transforms` constant. We
+  // cannot use `props.x` there as that refers to the component/element that is
+  // being transformed.
+  let context = {
+    node: props.node,
+    doc: { id: props.id, url: props.url, title: props.title },
+  };
 
   const transforms = {
-    Banner: props => <Banner {...props} />,
-    CodeBlock: props => {
+    Banner: (props) => <Banner {...props} />,
+    CodeBlock: (props) => {
       // When using <CodeBlock> directly within documents, its contents aren't
       // automatically protected from interpration as HTML, when they processed
       // by the DocTransformer. Thus we expect users to wrap their literal code
       // in <script> tags, which we again remove here.
       let children = props.children.replace(/^\s*<script>/, '').replace(/<\/script>\s*$/, '');
 
-      return <CodeBlock {...props} children={children} />;
+      return <CodeBlock {...props} {...context} children={children} />;
     },
-    ColorCard: props => <ColorCard {...props} />,
-    ColorGroup: props => <ColorGroup {...props} />,
-    Color: props => <Color {...props} />,
-    Playground: props => <Playground {...props} />,
-    Do: props => <Do {...props} />,
-    DoDontGroup: props => <DoDont {...props} />,
-    Dont: props => <Dont {...props} />,
-    FigmaEmbed: props => <FigmaEmbed {...props} />,
-    Image: props => <Image {...props} />,
-    TypographySpecimen: props => <TypographySpecimen {...props} />,
-    Warning: props => <Banner type="warning" {...props} />,
-    Glitch: props => <Glitch {...props} />,
-    CodeSandbox: props => <CodeSandbox {...props} />,
-    Asciinema: props => <Asciinema {...props} />,
-    ImageGrid: props => <ImageGrid {...props} />,
-    TableOfContents: props => <TableOfContents {...props} docTitle={docTitle} />,
-
-    a: props => <Link {...props} />,
-    h1: props => <Heading {...props} level="alpha" docTitle={docTitle} isJumptarget={true} />,
-    h2: props => <Heading {...props} level="beta" docTitle={docTitle} isJumptarget={true} />,
-    h3: props => <Heading {...props} level="gamma" docTitle={docTitle} isJumptarget={true} />,
-    h4: props => <Heading {...props} level="delta" docTitle={docTitle} isJumptarget={true} />,
-    img: props => <Image {...props} />,
-    pre: props => {
+    ColorCard: (props) => <ColorCard {...props} {...context} />,
+    ColorGroup: (props) => <ColorGroup {...props} {...context} />,
+    Color: (props) => <Color {...props} {...context} />,
+    Playground: (props) => <Playground {...props} {...context} />,
+    Do: (props) => <Do {...props} {...context} />,
+    DoDontGroup: (props) => <DoDont {...props} {...context} />,
+    Dont: (props) => <Dont {...props} {...context} />,
+    FigmaEmbed: (props) => <FigmaEmbed {...props} {...context} />,
+    Image: (props) => <Image {...props} {...context} />,
+    TypographySpecimen: (props) => <TypographySpecimen {...props} {...context} />,
+    Warning: (props) => <Banner type="warning" {...props} {...context} />,
+    Glitch: (props) => <Glitch {...props} {...context} />,
+    CodeSandbox: (props) => <CodeSandbox {...props} {...context} />,
+    Asciinema: (props) => <Asciinema {...props} {...context} />,
+    ImageGrid: (props) => <ImageGrid {...props} {...context} />,
+    TableOfContents: (props) => <TableOfContents {...props} {...context} />,
+
+    a: (props) => <Link {...props} {...context} />,
+
+    h1: (props) => <Heading {...props} {...context} level="alpha" isJumptarget={true} />,
+    h2: (props) => <Heading {...props} {...context} level="beta" isJumptarget={true} />,
+    h3: (props) => <Heading {...props} {...context} level="gamma" isJumptarget={true} />,
+    h4: (props) => <Heading {...props} {...context} level="delta" isJumptarget={true} />,
+
+    img: (props) => <Image {...props} {...context} />,
+    pre: (props) => {
       // When a language is added to a Markdown fenced code block, it is
       // stored as a class with a "language-" prefix in the inner <code>.
       // Here we extract it and turn it into a prop.
@@ -101,18 +105,18 @@ function Doc(props) {
       // empty "ghost" elements.
       let children = props.children.replace(/^<code>/, '').replace(/<\/code>$/, '');
 
-      return <CodeBlock escaped {...props} children={children} />;
+      return <CodeBlock escaped {...props} {...context} children={children} />;
     },
   };
 
   const orphans = Object.keys(transforms)
-    .filter(k => k !== 'a')
-    .filter(k => k !== 'Color')
-    .map(k => `p > ${k}`)
+    .filter((k) => k !== 'a')
+    .filter((k) => k !== 'Color')
+    .map((k) => `p > ${k}`)
     .concat(['p > video']);
 
   let transformedContent = transform(props.htmlContent, transforms, orphans, {
-    isPreformatted: type => type === 'pre' || type === 'CodeBlock'.toLowerCase(),
+    isPreformatted: (type) => ['pre', 'CodeBlock', 'Playground'].map((v) => v.toLowerCase()).includes(type),
     noTransform: (type, props) => {
       // This gets called on HTML elements that do not need
       // to be transformed to special React components.

frontend/src/Heading/index.js

@@ -28,12 +28,12 @@ function Heading(props) {
 
   let id = slugify(getNodeText(props.children));
 
-  let handleClick = ev => {
+  let handleClick = (ev) => {
     ev.preventDefault();
 
     let currentRouterState = props.router.getState();
     let currentNode = currentRouterState.params.node || '';
-    let t = slugify(props.docTitle) + '§' + id;
+    let t = slugify(props.doc.title) + '§' + id;
 
     props.router.navigate(
       'node',
@@ -59,7 +59,7 @@ function Heading(props) {
 
 export default withRoute(Heading);
 
-const getNodeText = node => {
+const getNodeText = (node) => {
   if (['string', 'number'].includes(typeof node)) return node;
   if (node instanceof Array) return node.map(getNodeText).join('');
   if (typeof node === 'object' && node) return getNodeText(node.props.children);