Merge pull request patternfly#246 from jeff-phillips-18/v6-updates

feat(update): Cherry pick missing v5 updates into main

README.md

@@ -1,61 +1,74 @@
-# @patternfly/react-topology
-
-This package provides Topology View components based on [PatternFly 4][patternfly-4]
-
-Based from https://github.com/patternfly/patternfly-react version 4.91.40 
+# PatternFly Topology
 
-### Prerequisites
+This package provides the resources necessary to use PatternFly Topology, an open source utility that you can use to create a visual representation of all the applications within your project, their build status, and the components and services associated with them.
 
-#### Node Environment
+Topology utilizes some of PatternFly's React components https://github.com/patternfly/patternfly-react.
 
-This project currently supports Node [Active LTS](https://github.com/nodejs/Release#release-schedule) releases. Please stay current with Node Active LTS when developing patternfly-react.
+Documentation for Topology and its features is available on [the PatternFly website.](www.patternfly.org/topology/about-topology)
 
-For example, to develop with Node 8, use the following:
+## Table of contents 
+- [Prerequisites](#prerequisites)
+- [Installing Topology](#installing-topology)
+- [Initial setup and usage](#initial-setup-and-usage)
+- [Example](#example)
+- [Demo app](#demo-app)
 
-```
-nvm install 8
-nvm use 8
-```
+## Prerequisites
 
-This project also requires a Yarn version of >=1.6.0. The latest version can be installed [here](https://yarnpkg.com/).
+To use Topology, you will need to have both [Node Active LTS](https://github.com/nodejs/Release#release-schedule) and [Yarn](https://yarnpkg.com/) installed.
 
-### Installing
+1. Install and develop with the most up-to-date version of Node Active LTS. For example, to develop with Node 8, you would use the following commands:
 
-```
-yarn add @patternfly/react-topology
-```
+    ```
+    nvm install 8
+    nvm use 8
+    ```
+1. Install and use version 1.6.0 or later of Yarn.
 
-or
+## Installing Topology
 
-```
-npm install @patternfly/react-topology --save
-```
+Once you have all of the prequisites, you can install the Topology package with Yarn or npm:
+
+1. Using Yarn:
 
-## Basic Usage
+    ```
+    yarn add @patternfly/react-topology
+    ```
+1. Using npm:
 
-To use React Topology out-of-the-box, you will first need to transform your back-end data into a [Model](https://github.com/patternfly/patternfly-react/blob/main/packages/react-topology/src/types.ts#L16-L20). These model objects contain the information needed to display the nodes and edges. Each node and edge has a set of properties used by PF Topology as well as a data field which can be used to customize the nodes and edges by the application.
+    ```
+    npm install @patternfly/react-topology --save
+    ```
 
-You will then need to declare a controller, which can be initialized via the `useVisualizationController()` method.
+## Initial setup and usage
 
-The `fromModel` method must be called on the controller to create the nodes. `fromModel` will take your data model as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type` and `layout`.
+To use Topology out of the box, follow these steps: 
 
-To create your topology view component, you can use `TopologyView` to Wrap `<VisualizationSurface>` which can accept `state` as a parameter. The state is application specific. It can be any data the application wants to store/retrieve from the controller. Adding state to the surface allows hooks to update when state changes. The state is useful to keep graph state such as selected elements.
+1. First transform your back-end data into a [Model](https://github.com/patternfly/react-topology/blob/main/packages/module/src/types.ts) object. This will contain the information needed to display the nodes and edges in your Topology view. Each node and edge contains a set of properties used by Topology, as well as a data field, which Topology can be used to customize the nodes and edges.
 
-Use a controller to wrap your topology view component. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context.
+1. Declare a controller, which can be initialized via the `useVisualizationController()` method.
 
-Three `register` methods are accessed by the controller.
+1. Create nodes by calling the `fromModel` method on the controller you initialized. `fromModel` will take the `Model` that you created as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`.
 
-The following two must be declared explicitly\:
+1. To create your Topology view component, wrap `TopologyView` around `<VisualizationSurface>`, which can accept a `state` parameter. 
+    - The value of state is application specific and should include any data the application wants to store/retrieve from the controller. 
+    - Adding state to  `<VisualizationSurface>` allows hooks to update when state changes. 
+    - State can also be used to keep track of your graph state, such as selected elements.
 
-- `registerLayoutFactory`\: This method sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options.
+1. Wrap your `TopologyView` with your controller. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context.
 
-- `registerComponentFactory`\: This method lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter.
+1. There are 3 `register` methods that the controller accesses.
 
-The register method below is initialized in `Visualization.ts`, therefore it doesn't need to be declared unless you want to support a custom implementation which modifies the types.
+    These 2 must be declared explicitly:
 
-- `registerElementFactory`\: This method sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`.
+    1. **`registerLayoutFactory`:** Sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options.
+    1. **`registerComponentFactory`:** Lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter.
+    
+    The remaining method is initialized in `Visualization.ts`, so it doesn't need to be declared unless you want to support a custom implementation that modifies the types:
 
-#### Example Component Usage
+    3. **`registerElementFactory`:** Sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`.
+
+## Example 
 
 ```ts
 import * as React from 'react';
@@ -185,3 +198,42 @@ export const TopologyBaselineDemo = React.memo(() => {
 });
 ```
 
+## Demo app
+
+To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained here.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts)
+
+Continue reading for instructions on how to build and run the demo app. 
+
+### Prerequisites
+
+In order to run the demo app, you need to make sure the following prerequisites are met. 
+
+1. Make sure that you have yarn installed, as outlined in [the general Topology prerequisites.](#prerequisites) 
+1. If you haven’t already, [fork the Topology project.](https://github.com/patternfly/react-topology)
+
+### Running the demo app
+
+Once you’ve set up the prerequisites, you can follow these steps to run the docs workspace or the demo app on your local machine
+
+1. In a terminal, type the following commands to start the docs workspace:
+
+```
+yarn install
+yarn start
+```
+
+2. In a terminal, type the following commands to navigate to demo-app-ts and launch the demo app:
+
+```
+cd packages/demo-app-ts
+yarn start:demo-app:hot
+```
+
+3. You will receive a message confirming that the app is running. To view the locally running workspace, visit http://localhost:8008/.
+
+4. Explore the demo app in your browser:
+
+![Demo app landing page.](packages/module/patternfly-docs/content/examples/img/topology-demo-app.png)
+
+## Need help? 
+If you find a bug, have a request, or have any questions about Topology that aren't answered in our documentation, please [reach out to us on Slack.](https://patternfly.slack.com/archives/CK7URGJ2W)

packages/demo-app-ts/README.md

@@ -0,0 +1,50 @@
+# Topology demo app
+
+To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained here.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts)
+
+Continue reading for instructions on how to build and run the demo app. 
+
+### Prerequisites
+
+In order to run the demo app, you need to make sure the following prerequisites are met. 
+
+1. Make sure that you have yarn installed, as outlined in [the general Topology prerequisites.](#prerequisites) 
+1. Make sure that you have the PatternFly React library installed. [Follow these instructions if you need to install this package.](https://github.com/patternfly/patternfly-react?tab=readme-ov-file#install-and-configure-patternfly-react)
+1. If you haven’t already, clone [the Topology project](https://github.com/patternfly/react-topology) and navigate to your local directory:
+
+``` 
+git clone https://github.com/patternfly/react-topology.git
+cd react-topology
+```
+
+### Running the demo app
+
+Once you’ve set up the prerequisites, you can follow these steps to run the demo app on your local machine
+
+1. In a terminal, type the following commands to start the docs workspace:
+
+```
+yarn install
+yarn start
+```
+
+2. In a separate terminal window, type the following commands to navigate to demo-app-ts and launch the demo app:
+
+```
+cd packages/demo-app-ts
+yarn start:demo-app:hot
+```
+
+3. You will receive a message confirming that the app is running, as well the URL that you can enter in your browser to load the app:
+
+```
+<i> [webpack-dev-server] Project is running at:
+<i> [webpack-dev-server] Loopback: http://localhost:3000/
+```
+
+4. Explore the demo app in your browser:
+
+![Demo app landing page.](packages/module/patternfly-docs/content/examples/img/topology-demo-app.png)
+
+## Need help? 
+If you find a bug, have a request, or have any questions about Topology that aren't answered in our documentation, please [reach out to us on Slack.](https://patternfly.slack.com/archives/CK7URGJ2W)

packages/demo-app-ts/src/demos/pipelineGroupsDemo/DemoTaskGroup.tsx

@@ -15,6 +15,7 @@ import {
   RunStatus,
   TaskGroupPillLabel
 } from '@patternfly/react-topology';
+import { BanIcon } from '@patternfly/react-icons';
 import { DEFAULT_TASK_HEIGHT, GROUP_TASK_WIDTH } from './createDemoPipelineGroupsNodes';
 
 type DemoTaskGroupProps = {
@@ -43,12 +44,18 @@ const DemoTaskGroup: React.FunctionComponent<DemoTaskGroupProps> = ({ element, .
         collapsible
         collapsedWidth={GROUP_TASK_WIDTH}
         collapsedHeight={DEFAULT_TASK_HEIGHT}
-        GroupLabelComponent={TaskGroupPillLabel}
+        GroupLabelComponent={(props) => (
+          <TaskGroupPillLabel
+            {...props}
+            customStatusIcon={data.status === RunStatus.Cancelled ? <BanIcon /> : undefined}
+          />
+        )}
         element={element as Node}
         centerLabelOnEdge
         recreateLayoutOnCollapseChange
         getEdgeCreationTypes={getEdgeCreationTypes}
         scaleNode={hover && detailsLevel !== ScaleDetailsLevel.high}
+        customStatusIcon={data.status === RunStatus.Cancelled ? <BanIcon /> : undefined}
         showLabelOnHover
         hideDetailsAtMedium
         showStatusState

packages/demo-app-ts/src/demos/pipelineGroupsDemo/DemoTaskNode.tsx

@@ -4,13 +4,15 @@ import {
   DEFAULT_LAYER,
   GraphElement,
   Layer,
+  RunStatus,
   ScaleDetailsLevel,
   TaskNode,
   TOP_LAYER,
   useHover,
   WithContextMenuProps,
   WithSelectionProps
 } from '@patternfly/react-topology';
+import { BanIcon } from '@patternfly/react-icons';
 
 type DemoTaskNodeProps = {
   element: GraphElement;
@@ -31,6 +33,7 @@ const DemoTaskNode: React.FunctionComponent<DemoTaskNodeProps> = ({ element, ...
           showStatusState
           status={data.status}
           hideDetailsAtMedium
+          customStatusIcon={data.status === RunStatus.Cancelled ? <BanIcon /> : undefined}
           {...rest}
         />
       </g>

packages/demo-app-ts/src/demos/pipelineGroupsDemo/createDemoPipelineGroupsNodes.ts

@@ -159,7 +159,7 @@ export const createExecution3 = (runAfter?: string): [string, PipelineNodeModel[
     },
     runAfterTasks: [task_3_1.id],
     data: {
-      status: RunStatus.Succeeded,
+      status: RunStatus.Cancelled,
       isDependency: true
     }
   };
@@ -294,7 +294,7 @@ export const createExecution3 = (runAfter?: string): [string, PipelineNodeModel[
       padding: [NODE_PADDING_VERTICAL, NODE_PADDING_HORIZONTAL]
     },
     data: {
-      status: RunStatus.Succeeded,
+      status: RunStatus.Cancelled,
       isDependency: true
     }
   };

packages/module/patternfly-docs/content/examples/AboutTopology.md

@@ -0,0 +1,106 @@
+---
+id: About Topology
+section: topology
+sortValue: 1
+sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyGettingStartedDemo.tsx
+propComponents: ['VisualizationProvider', 'VisualizationSurface']
+---
+
+import {
+  ColaLayout,
+  DefaultEdge,
+  DefaultGroup,
+  DefaultNode,
+  EdgeStyle,
+  GraphComponent,
+  ModelKind,
+  NodeShape,
+  SELECTION_EVENT,
+  Visualization,
+  VisualizationProvider,
+  VisualizationSurface
+} from '@patternfly/react-topology';
+import Icon1 from '@patternfly/react-icons/dist/esm/icons/regions-icon';
+import Icon2 from '@patternfly/react-icons/dist/esm/icons/folder-open-icon';
+
+import './topology-example.css';
+
+# Introduction
+
+**Note:** Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology).
+
+PatternFly's **Topology** is an open source utility built off of [@patternfly/react-core](https://www.npmjs.com/package/@patternfly/react-core) that you can use to create a visual representation of all the applications within your project, their build status, and the components and services associated with them. Creating these visuals can help document and communicate the intricacies of the processes behind your product.
+
+To create a Topology view for your application, you can create a simple layout of nodes, which represents your data points, and connecting edges, which represent the relationships between nodes. Beyond this basis, you can continue to customize and enhance your Topology view to fit the specific needs of your application.
+
+## Prerequisites
+
+To use Topology, you will need to have both [Node Active LTS](https://github.com/nodejs/Release#release-schedule) and [Yarn](https://yarnpkg.com/) installed.
+
+1. Install and develop with the most up-to-date version of Node Active LTS. For example, to develop with Node 8, you would use the following commands:
+
+    ```
+    nvm install 8
+    nvm use 8
+    ```
+2. Install and use version 1.6.0 or later of Yarn.
+
+## Installing Topology
+
+Once you have all of the prequisites, you can install the Topology package with Yarn or npm:
+
+1. Using Yarn:
+   
+    ```
+    yarn add @patternfly/react-topology
+    ```
+2. Using npm:
+   
+    ```
+    npm install @patternfly/react-topology --save
+    ```
+
+## Initial setup and usage
+
+To use Topology out of the box, follow these steps: 
+
+1. First transform your back-end data into a [Model](https://github.com/patternfly/react-topology/blob/main/packages/module/src/types.ts) object. This will contain the information needed to display the nodes and edges in your Topology view. Each node and edge contains a set of properties used by Topology, as well as a data field, which Topology can be used to customize the nodes and edges.
+
+1. Declare a controller, which can be initialized via the `useVisualizationController()` method.
+
+1. Create nodes by calling the `fromModel` method on the controller you initialized. `fromModel` will take the `Model` that you created as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`.
+
+1. To create your Topology view component, wrap `TopologyView` around `<VisualizationSurface>`, which can accept a `state` parameter.
+    - The value of state is application specific and should include any data the application wants to store/retrieve from the controller.
+    - Adding state to  `<VisualizationSurface>` allows hooks to update when state changes.
+    - State cam also be used to keep track of your graph state, such as selected elements.
+
+1. Wrap your `TopologyView` with your controller. In the example below, this is done via the `VisualizationProvider` which consumes the `Controller` via context.
+
+1. There are 3 `register` methods that the controller accesses.
+
+    These 2 must be declared explicitly:
+
+    1. **`registerLayoutFactory`:** Sets the layout of your topology view (e.g. Force, Dagre, Cola, etc.). You can use `defaultLayoutFactory` as a parameter if your application supports all layouts. You can also update `defaultLayout` to a custom implementation if you only want to support a subset of the available layout options.
+    1. **`registerComponentFactory`:** Lets you customize the components in your topology view (e.g. nodes, groups, and edges). You can use `defaultComponentFactory` as a parameter.
+    
+    The remaining method is initialized in `Visualization.ts`, so it doesn't need to be declared unless you want to support a custom implementation that modifies the types:
+
+    3. **`registerElementFactory`:** Sets the types of the elements being used (e.g. graphs, nodes, edges). `defaultElementFactory` uses types from `ModelKind` and is exported in `index.ts`.
+
+1. Create nodes by calling the `fromModel` method on the controller. `fromModel` will take your data model as a parameter. Your data model should include a `graph` object, on which you will need to set `id` , `type`, and `layout`.
+
+1. To create your topology view component, add a `<VisualizationProvider>`, which is a useful context provider. It allows access to the created controller and is required when using the `<VisualizationSurface>` component.
+
+1. Use `<VisualizationSurface>` to provide the SVG component required for your topology components. `<VisualizationSurface>` can take a state parameter, which enables you to pass your state settings to the controller.
+
+## Demo app
+
+To help you better understand and visualize the different Topology components, we have created an interactive demo, [which is contained in the react-topology repository.](https://github.com/patternfly/react-topology/tree/main/packages/demo-app-ts)
+
+You can run the demo app [by following these instructions.](https://github.com/patternfly/react-topology?tab=readme-ov-file#demo-app)
+
+### Example
+
+```ts file='./TopologyGettingStartedDemo.tsx'
+```