docs(installation/javascript): improve installation guide (#295)

Co-authored-by: Lukas Maurer <lukas.maurer@siemens.com>
siemens · Jan 13, 2023 · 9ccddb1 · 9ccddb1
1 parent ae263fa
commit 9ccddb1
Show file tree

Hide file tree

Showing 5 changed files with 104 additions and 44 deletions.
diff --git a/packages/documentation/docs/installation/javascript.md b/packages/documentation/docs/installation/javascript.md
@@ -4,41 +4,68 @@ sidebar_title: JavaScript
 title: JavaScript
 ---
 
-### Installation
+import Playground from '@site/src/components/Playground';
+import WebComponentButtons from '../auto-generated/previews/web-component/buttons.md'
+
+## Installation
 
 Install `@siemens/ix` and `@siemens/ix-icons` using a package manager:
 
-#### npm
+### npm
 
 ```
 npm i -S @siemens/ix @siemens/ix-icons
 ```
 
-#### yarn
+### yarn
 
 ```
 yarn add @siemens/ix @siemens/ix-icons
 ```
 
-## Load styles and scripts
+## Build
+
+There are several different possibilities to build and serve web apps with the library.
+In the following section we will describe how you can build an application with [vite](https://vitejs.dev/guide/).
 
-### Load web fonts
+`index.html`
 
 ```html
-<link rel="stylesheet" href="lib/ix-icons/dist/css/ix-icons.css" />
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div>
+      <ix-button class="m-1" variant="primary">Button</ix-button>
+      <ix-button class="m-1" variant="primary" disabled>Button</ix-button>
+    </div>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>
 ```
 
-### Load common style sheet
+`main.js`
 
-```html
-<link rel="stylesheet" href="lib/ix/dist/siemens-ix/siemens-ix.css" />
+```javascript
+import '@siemens/ix-icons/dist/css/ix-icons.css';
+import '@siemens/ix/dist/siemens-ix/siemens-ix.css';
+import { applyPolyfills, defineCustomElements } from '@siemens/ix/loader';
+
+(async () => {
+  await applyPolyfills();
+  await defineCustomElements();
+})();
 ```
 
-### Load `ix` Web Components
+## Example
 
-```html
-<script type="module">
-  import { defineCustomElements } from './lib/ix/loader/index.js';
-  defineCustomElements();
-</script>
-```
+<Playground
+name="buttons"
+availableFrameworks={["javascript"]}
+frameworks={{
+  javascript: WebComponentButtons
+}}>
+</Playground>
diff --git a/packages/documentation/src/components/Playground/index.tsx b/packages/documentation/src/components/Playground/index.tsx
@@ -90,6 +90,7 @@ interface PlaygroundProps {
     angular?: Record<string, MdxContent> | MdxContent;
     webcomponents?: Record<string, MdxContent> | MdxContent;
   };
+  availableFrameworks?: TargetFramework[];
 }
 
 function getPathId(pathname: string) {
@@ -136,20 +137,31 @@ function FileTabs(props: {
   );
 }
 
+function getDefaultTargetFramework(availableFrameworks?: TargetFramework[]) {
+  if (!availableFrameworks) {
+    return TargetFramework.ANGULAR;
+  }
+  return (
+    (availableFrameworks.length !== 0 ? availableFrameworks[0] : undefined) ||
+    TargetFramework.ANGULAR
+  );
+}
+
 export default function Playground({
   name,
   height,
   noMargin,
   theme,
   frameworks,
   hideInitalCodePreview,
+  availableFrameworks,
 }: DemoProps & PlaygroundProps) {
   const { pathname } = useLocation();
   const baseUrl = useBaseUrl('/');
   const [showCode, setShowCode] = useState<boolean>(!hideInitalCodePreview);
 
   const [targetFramework, setTargetFramework] = useState<TargetFramework>(
-    TargetFramework.ANGULAR
+    getDefaultTargetFramework(availableFrameworks)
   );
 
   const [sourceCodeSnippets, setSourceCodeSnippets] = useState<
@@ -245,6 +257,16 @@ export default function Playground({
     return sourceCodeSnippets[targetFramework].map((file) => file.filename);
   }
 
+  function isFrameworkConfigured(framework: TargetFramework) {
+    if (!availableFrameworks) {
+      return true;
+    }
+    return (
+      availableFrameworks.length === 0 ||
+      availableFrameworks.includes(framework)
+    );
+  }
+
   return (
     <div className="Playground">
       <div className="Playground__Toolbar Location__Top">
@@ -259,27 +281,36 @@ export default function Playground({
       {showCode ? (
         <>
           <div className="Playground__Toolbar Location__Bottom">
-            <IxButton
-              className="Playground__Framework__Button"
-              ghost={targetFramework !== TargetFramework.ANGULAR}
-              onClick={() => changeFramework(TargetFramework.ANGULAR)}
-            >
-              Angular
-            </IxButton>
-            <IxButton
-              className="Playground__Framework__Button"
-              ghost={targetFramework !== TargetFramework.REACT}
-              onClick={() => changeFramework(TargetFramework.REACT)}
-            >
-              React
-            </IxButton>
-            <IxButton
-              className="Playground__Framework__Button"
-              ghost={targetFramework !== TargetFramework.JAVASCRIPT}
-              onClick={() => changeFramework(TargetFramework.JAVASCRIPT)}
-            >
-              JavaScript
-            </IxButton>
+            {isFrameworkConfigured(TargetFramework.ANGULAR) ? (
+              <IxButton
+                className="Playground__Framework__Button"
+                ghost={targetFramework !== TargetFramework.ANGULAR}
+                onClick={() => changeFramework(TargetFramework.ANGULAR)}
+              >
+                Angular
+              </IxButton>
+            ) : null}
+
+            {isFrameworkConfigured(TargetFramework.REACT) ? (
+              <IxButton
+                className="Playground__Framework__Button"
+                ghost={targetFramework !== TargetFramework.REACT}
+                onClick={() => changeFramework(TargetFramework.REACT)}
+              >
+                React
+              </IxButton>
+            ) : null}
+
+            {isFrameworkConfigured(TargetFramework.JAVASCRIPT) ? (
+              <IxButton
+                className="Playground__Framework__Button"
+                ghost={targetFramework !== TargetFramework.JAVASCRIPT}
+                onClick={() => changeFramework(TargetFramework.JAVASCRIPT)}
+              >
+                JavaScript
+              </IxButton>
+            ) : null}
+
             <div className="Playground__Toolbar__Actions">
               <ButtonOpenGithub name={name} framework={targetFramework} />
               <ButtonOpenStackBlitz

diff --git a/packages/documentation/static/code-runtime/angular/package.json b/packages/documentation/static/code-runtime/angular/package.json
@@ -16,9 +16,9 @@
     "@angular/platform-browser-dynamic": "^15.0.0",
     "@angular/router": "^15.0.0",
     "@popperjs/core": "^2.11.6",
-    "@siemens/ix": "^1.1.1",
-    "@siemens/ix-angular": "^1.1.1",
-    "@siemens/ix-icons": "^1.0.2",
+    "@siemens/ix": "^1",
+    "@siemens/ix-angular": "^1",
+    "@siemens/ix-icons": "^1",
     "rxjs": "~7.5.0",
     "tslib": "^2.3.0",
     "zone.js": "~0.12.0"

diff --git a/packages/documentation/static/code-runtime/html/package.json b/packages/documentation/static/code-runtime/html/package.json
@@ -11,7 +11,7 @@
   ],
   "devDependencies": {
     "vite": "^3.1.0",
-    "@siemens/ix": "1.2.0-beta.0",
-    "@siemens/ix-icons": "~1.0.0"
+    "@siemens/ix": "^1",
+    "@siemens/ix-icons": "^1"
   }
 }
diff --git a/packages/documentation/static/code-runtime/react/package.json b/packages/documentation/static/code-runtime/react/package.json
@@ -11,7 +11,9 @@
     "react-scripts": "5.0.1",
     "typescript": "^4.6.4",
     "web-vitals": "^2.1.4",
-    "@siemens/ix-react": "^1.1.1"
+    "@siemens/ix": "^1",
+    "@siemens/ix-icons": "^1",
+    "@siemens/ix-react": "^1"
   },
   "scripts": {
     "start": "react-scripts start",