#1701 Elyra Canvas Documentation using mkdocs (#1702)

Author: srikant-ch5

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: ci 
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force

.gitignore

@@ -47,6 +47,9 @@ build/Release
 # Dependency directory
 node_modules
 
+# Site folder generated by mkdocs-deploy
+site
+
 config/app-local.json
 
 /public/build/*

README.md

@@ -37,7 +37,7 @@ npm install -g grunt-cli sass
 ```
 In your application's package.json replace  
 ```
-"@elyra/canvas": "<verson>"
+"@elyra/canvas": "<version>"
 ```
 with
 ```  
@@ -50,3 +50,19 @@ Delete @elyra/canvas from node_modules of your application
 # Run npm install to get local copy of common-canvas and/or common-properties
 npm install
 ```
+
+### Contribute to the Elyra Canvas documentation (mkdocs)
+1. Python v3 needs to be available.
+2. Go to canvas directory.
+
+3. Install required mkdocs packages using pip3.
+```
+pip3 install -r requirements.txt`
+```
+
+4. Run below command to start mkdocs server.
+```
+mkdocs serve
+```
+
+5. When complete, open the browser: http://127.0.0.1:8000/

docs/2.0-Common-Canvas-Documentation.md

@@ -0,0 +1,241 @@
+## Introduction
+Common canvas displays a flow of data operations as nodes and links which the user can create and edit to get the flow they want. These visual flows of data operations are translated into data processing steps performed by a back-end server. Common canvas provides functionality for the visual display of flows in the browser and leaves persistence and execution of data flows to the application.
+Within common canvas the user can perform operations such as:
+
+* Create a new node by dragging a node definition from a palette onto the canvas.
+* Create a new node by dragging a node from outside the canvas onto the canvas (you'll have to do some programming to get this to work).
+* Delete a node by clicking a context menu option.
+* Create a link by dragging a line from one node to another.
+* Delete a link by clicking a context menu option.
+* Add a comment to the canvas and draw a link from it to one or more nodes.
+* Edit a comment.
+* Move nodes and comments around in the canvas to get the desired arrangement.  
+* And more! ...
+
+# Architecture
+
+## Common Canvas react object
+   Common-canvas is a react component that can be used in your react application to display a fully-functional canvas user interface including the function mentioned above. The `<CommonCanvas>` component is displayed in a `<div>` provided by your application. 
+
+Common-canvas has these constituent parts that are visible to the user:
+
+* [Canvas editor](2.0.1-Canvas-Editor.md) - the main area of the UI where the flow is displayed and edited
+* [Palette](2.0.2-Palette.md) - a set of node templates that can be dragged to the canvas to create new nodes
+* [Context menu](2.0.3-Context-Menu.md) - a menu of options for nodes, comments, etc
+* [Context toolbar](2.0.4-Context-Toolbar.md) - a menu of options for nodes, comments, etc presented as a small toolbar
+* Toolbar - a set of tools across the top of the UI
+* Notification panel - a panel for displaying runtime and other messages to your user
+* Right side flyout - a panel, often used to display node properties
+* Top panel - a panel which can be used to display other app related information
+* Bottom panel - a panel which can be used to display other app related information
+
+and it handles: 
+
+  1. the visual display of the flow of operations;
+  2. any user gestures on the canvas;
+  3. display of context menus;
+  4. display and handling of the palette.
+  5. provision of callbacks to tell your code what operations the user is performing on the canvas
+  6. and much much more.
+
+## Canvas Controller
+
+The only mandatory parameter for the `<CommonCanvas>` component is a regular JavaScript object called the [CanvasController](2.4-Canvas-Controller-API.md).
+
+  The CanvasController routes handles calls from the host application and actions performed by the user. It then updates the internal object model which stores:
+
+  1. the data that describes the flow of nodes, links and comments (called a pipelineFlow);
+  2. the data that describes the definition of the palette which contains node templates that can dragged to add nodes to the canvas;
+  3. the set of currently selected objects.
+  4. notification messages
+  5. breadcrumbs that indicate which sub-flow is being viewed
+  6. layout information
+
+  The [CanvasController](2.4-Canvas-Controller-API.md) provides an API which allows your code to:
+
+   1. set a new pipelineFlow;
+   2. get the current pipelineFlow (after the user has edited it);
+   3. update and edit objects in the canvas (for example, add node, delete link etc.);
+   4. set the node definition data (for display of nodes in the palette)
+
+# Getting started with common canvas programming
+
+## Hello Canvas!
+  You can start by looking at these two 'hello  world' examples for using common canvas:
+
+* This first one called [app-tiny.js](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/client/app-tiny.js) has the bare minimum necessary to get a fully functioning common-canvas to appear including all the basic functionality, a palette and a flow of nodes and links. 
+* The second, called [app-small.js](https://github.com/elyra-ai/canvas/blob/master/canvas_modules/harness/src/client/app-small.js), shows many of the options available to a common-canvas developer such as configurations and callback handlers.
+
+You can also look at the [App.js](https://github.com/elyra-ai/canvas/blob/49ed634e3353d8f5c58eb8409ed8e1009f19c87a/canvas_modules/harness/src/client/App.js) file in the test harness section of this repo to see examples of code that uses the common canvas component.
+
+   Now let's walk through the different steps to get common-canvas working:
+
+
+## Step 1 : Install Elyra Canvas NPM module
+
+Enter:
+```
+     npm install @elyra/canvas 
+```
+
+## Step 2 : Import Common-canvas
+
+To use common canvas in your react application you need to do the following. First import the CommonCanvas react component and CanvasController class from the Elyra Canvas library.  Elyra Canvas produces both `esm` and `cjs` outputs.  By default `esm` will be used when webpack is used to build the consuming application.
+
+**All Components**
+```js
+    import { CommonCanvas, CanvasController } from "@elyra/canvas";
+```
+**Canvas only**
+
+ To import only canvas functionality in `cjs` format use:
+```js
+    import { CommonCanvas, CanvasController } from "@elyra/canvas/dist/lib/canvas";
+```
+
+In addition you'll need to import `<IntlProvider>` from the `react-intl` library.
+```js
+    import { IntlProvider } from "react-intl";
+```
+
+
+## Step 3 : Create an instance of the canvas controller
+To control the canvas you'll need an instance of the canvas controller so create an instance of it like this (probably in the constructor of your object).
+```js
+    this.canvasController = new CanvasController();
+```
+## Step 4 : Set the palette data
+Next you'll need to populate the palette data. This will specify the nodes (split into categories) that will appear in the palette. The user can drag them from the palette to build their flow. This is done by calling CanvasController with:
+```js
+    this.canvasController.setPipelineFlowPalette(pipelineFlowPalette);
+```
+The pipelineFlowPalette object should conform to the JSON schema found here:    
+https://github.com/elyra-ai/pipeline-schemas/tree/master/common-canvas/palette
+
+Some examples of palette JSON files can be found here:    
+https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/palettes
+
+## Step 5 : (Optional) Set the flow data
+This is an optional step. If you want a previously saved flow to be shown in the canvas editor so the user can start to edit it, you will need to call the CanvasController with:
+```js
+    this.canvasController.setPipelineFlow(pipelineFlow);
+```
+
+The pipelineFlow object should conform to the JSON schema found here:    
+https://github.com/elyra-ai/pipeline-schemas/tree/master/common-pipeline/pipeline-flow
+
+Some examples of pipeline flow JSON files can be found here:    
+https://github.com/elyra-ai/canvas/tree/master/canvas_modules/harness/test_resources/diagrams
+
+## Step 6 : Pull in the CSS
+Check this section to find info on what CSS to include in your application's CSS. [Styling](4.0-Styling.md).
+
+## Step 7 : Display the canvas
+
+Finally you'll need to display the canvas object inside an `<IntlProvider>` object. Inside your render code, add the following:
+```html
+    <div>
+        <IntlProvider>
+            <CommonCanvas canvasController={this.canvasController} />
+        </IntlProvider>
+    </div>
+```
+The div should have the dimensions you want for your canvas to display in your page. For the canvasController property, pass the instance of canvas controller you created earlier. This is the only mandatory property. After providing this and running your code you will have a fully functioning canvas including: a palette; default toolbar; context menus; direct manipulation (move and resize) etc. To customize these behaviors and presentation continue with the sections below.
+
+## Common Canvas customization
+If you want to customize the behavior of common canvas you can specify any combination of the following optional settings:   
+```html
+    <div>
+        <CommonCanvas
+            canvasController={this.canvasController}
+
+            config={this.commonCanvasConfig}
+            toolbarConfig={this.toolbarConfig}
+            notificationConfig={this.notificationConfig}
+            contextMenuConfig={this.contextMenuConfig}
+            keyboardConfig={this.keyboardConfig}
+
+            contextMenuHandler={this.contextMenuHandler}
+            beforeEditActionHandler={this.beforeEditActionHandler}
+            editActionHandler={this.editActionHandler}    
+            clickActionHandler={this.clickActionHandler}   
+            decorationActionHandler={this.decorationActionHandler}
+            layoutHandler={this.layoutHandler}  
+            tipHandler={this.tipHandler}
+            idGeneratorHandler={this.idGeneratorHandler}
+            selectionChangeHandler={this.selectionChangeHandler}
+            actionLabelHandler={this.actionLabelHandler}
+
+            showRightFlyout={showRightFlyout}
+            rightFlyoutContent={rightFlyoutContent}
+
+            showBottomPanel={showBottomPanel}
+            bottomPanelContent={bottomPanelContent}
+
+            showTopPanel={showTopPanel}
+            topPanelContent={topPanelContent}
+        >
+        </CommonCanvas>
+    </div>
+```
+
+### Config objects
+Common canvas has five **optional** configuration objects: config, toolbarConfig, notificationConfig, contextMenuConfig and keyboardConfig.
+They are documented here:
+[Config Objects](2.1-Config-Objects.md)
+
+### Handlers
+There are several **optional** handlers implemented as callback functions. They are contextMenuHandler, editActionHandler, beforeEditActionHandler, clickActionHandler, decorationActionHandler, layoutHandler, tipHandler, idGeneratorHandler, selectionChangeHandler and actionLabelHandler. They are documented here:
+[Common Canvas Callback](2.2-Common-Canvas-callbacks.md)
+
+### Right-flyout panel parameters
+The right flyout panel appears on the right of the canvas area. You can add whatever content you like to this panel. Typically, it is used to display properties of nodes on the canvas. There are two **optional** parameters to let you manage the right flyout panel These are:
+
+- showRightFlyout: This can be true or false to indicate whether the flyout panel is shown or not. The default is false.
+- rightFlyoutContent: content to display in the right flyout which is a JSX object. Nothing is displayed by default.
+
+### Bottom panel parameters
+The bottom panel appears below the canvas area and between the palette and the right flyout panel. You can add whatever content you like to this panel. There are two **optional** parameters to let you manage the bottom panel. These are:
+
+- showBottomPanel: This can be true or false to indicate whether the bottom panel is shown or not. The default is false.
+- bottomPanelContent: content to display in the bottom panel which is a JSX object. Nothing is displayed by default.
+
+### Top panel parameters
+The top panel appears below the toolbar and between the palette and the right flyout panel. You can add whatever content you like to this panel. There are two **optional** parameters to let you manage the top panel. These are:
+
+- showTopPanel: This can be true or false to indicate whether the top panel is shown or not. The default is false.
+- topPanelContent: content to display in the top panel which is a JSX object. Nothing is displayed by default.
+
+### Localization
+You can customize `<CommonCanvas>` using the `<IntlProvider>` object to [display translated test](#localization)
+
+## Creating nodes on the canvas
+
+Nodes can be created on the canvas by the user in two ways:
+
+* By dragging a node from the palette onto the canvas background
+* By dragging a node from outside the canvas
+
+The first technique is provided by Common canvas. The second requires some development work which is documented here:
+[Enabling node creation from external object](2.3-Enabling-node-creation-from-external-object.md)
+
+
+## Keyboard support
+
+Common canvas supports a number of keyboard interactions as follows:
+
+|Keyboard Shortcut|Action|Description|
+|---|---|---|
+|Ctrl/Cmnd + a|selectAll|Select All objects   
+|delete|deleteSelectedObjects|Delete currently selected objects|
+|Ctrl/Cmnd + x|cut|Cut selected objects to the clipboard|
+|Ctrl/Cmnd + c|copy|Copy selected objects to the clipboard|
+|Ctrl/Cmnd + v|paste|Paste objects from the clipboard. If the mouse cursor is over <br>the canvas, objects will be pasted at the cursor position or, <br>if not, at a default position|
+|Ctrl/Cmnd + z|undo|Undo last command|
+|Ctrl/Cmnd + Shift + z|redo|Redo last undone command|
+|Ctrl/Cmnd + y|redo|Redo last undone command|
+
+
+Your application can disable any or all of these actions by providing the [keyboard config object](2.1-Config-Objects.md#keyboard-config-object) to the CommonCanvas react component.
+
+When any of the shortcut keys are pressed the common-canvas object model will be updated and then the [editActionHandler](2.2-Common-Canvas-callbacks.md#editactionhandler) callback will be called with the `data.editType` parameter set to the action above and the `data.editSource` parameter set to "keyboard".

docs/2.0.1-Canvas-Editor.md

@@ -0,0 +1,11 @@
+The Canvas Editor displays the flow to the user and allows the user to interact with the flow using the mouse/trackpad and the keyboard.
+
+The editor displays the following object types which the user can interact with:
+
+## Nodes
+## Links
+## Comments
+## The Canvas background
+
+
+[Still under construction]

docs/2.0.1.1-Nodes.md

@@ -0,0 +1 @@
+[Under construction]