Docs(Topology): Edits content as part of audit. (patternfly#197)

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/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'
+```

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

@@ -5,8 +5,6 @@ sortValue: 13
 sourceLink: https://github.com/patternfly/react-topology/blob/main/packages/module/patternfly-docs/content/examples/TopologyAnchorsDemo.tsx
 ---
 
-Note: Topology lives in its own package at [`@patternfly/react-topology`](https://www.npmjs.com/package/@patternfly/react-topology)
-
 import {
   AbstractAnchor,
   AnchorEnd,
@@ -28,26 +26,34 @@ import {
 
 import './topology-example.css';
 
-### Using custom anchors
+# Introduction
+
+An **anchor** is the point at which an edge connects to a node.
+
+By default, nodes use a `CenterAnchor`, which refers to the center of the bounds of the node. You can use different anchors for different node shapes.
+
+## Using custom anchors
+
+You can customize the start and end points for a node edge by specifying the anchors.
 
-By default, Nodes use a default anchor `CenterAnchor` which use the center of the bounds of the node. A variety of anchors are provided for different node shapes that will set the anchor locations to the edge of the node.
+You can specify the SVG element that determines edge locations by using the provided hooks: 
+- **`usePolygonAnchor`**
+- **`useSvgAnchor`**
+- **`useAnchor`:** Allows you to specify your own custom anchor or provide a function that returns a specific anchor.
+  - This is useful for adjusting the anchor based on the node being displayed.
 
-You can customize the start and end locations for edges on a node by specifying the anchors to use on the node.
+These hooks accept the following parameters, allowing you to customize the anchor:
 
-Hooks are provided to enable you to specify the SVG element you wish to use for determining the edge locations: `usePolygonAnchor`, and `useSvgAnchor`
-These hooks accept parameters allowing you to customize when to use the anchor:
-- `points` (usePolygonAnchor only) to specify the points for the polygon
-- `AnchorEnd` to specify use for start, end or both
-- `type` to specify which edge types to use the anchor for (optional)
+- **`points` (for `usePolygonAnchor` only):** The points for the polygon.
+- **`AnchorEnd`:** Use for start, end, or both.
+- **`type` (optional):** Which edge types to use the anchor for.
 
-The `useAnchor` hook allows you to specify your own custom anchor or provide a function to return a specific anchor (useful for adjusting the anchor based on the node being displayed).
+A custom anchor must extend the `AbstractAnchor` class. There are 2 methods used for anchors:
 
-A custom anchor must extend the `AbstractAnchor` class. There are two methods used for anchors:
+- **`getLocation(reference: Point): Point`:** Return the location of the anchor, based on the incoming reference point. Default anchors use the point on the node border closest to the reference point.
+- **`getReferencePoint(): Point`:** Return the location where outgoing edges initiate from.
 
-- `getLocation(reference: Point): Point`
-  - Should return the location of the anchor based on the incoming reference point. Default anchors use the point on the node border closest to the reference point.
-- `getReferencePoint(): Point`
-  - Should return the location where outgoing edges would initiate from
+### Example
 
 ```ts file="./TopologyAnchorsDemo.tsx"
 ```