UI/doc reorg (iTwin#2843)

* WIP to merge.

* Remove deprecated components from learning docs.

* Fix some broken links

* Fix borken links

* Fix links

* Test of using codes intead of dashes.

* Fix links with dashes in dir names

* Update from PR comments

* Rush change

common/changes/@itwin/appui-react/ui-doc-reorg_2021-12-10-16-27.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@itwin/appui-react",
+      "comment": "Update links in API doc comments.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@itwin/appui-react"
+}

docs/changehistory/2.17.0.md

@@ -45,7 +45,7 @@ A reality model displaying simple building meshes for locations all over the wor
 
 ## Popout Widgets
 
-IModelApps, that use AppUi version "2", can now specify if a Widget can support being "popped-out" to a child popup window. The child window runs in the same javascript context as the parent application window. See [Child Window Manager]($docs/learning/ui/framework/ChildWindows.md) for more details.
+IModelApps, that use AppUi version "2", can now specify if a Widget can support being "popped-out" to a child popup window. The child window runs in the same javascript context as the parent application window. See [Child Window Manager]($docs/learning/ui/appui/appui‑react/ChildWindows.md) for more details.
 
 ## External textures
 

docs/learning/ui/AugmentingUI.md

@@ -152,4 +152,4 @@ ReducerRegistryInstance.registerReducer(
 );
 ```
 
-See complete [example](./framework/state/#example-of-defining-dynamic-reducer-needed-by-a-package).
+See complete [example](./appui/appui‑react/State.md##example‑of‑defining‑dynamic‑reducer‑needed‑by‑a‑package).

docs/learning/ui/HostAppUI.md

@@ -6,13 +6,13 @@ The following topics provide information to help ensure the host iModelApp is pr
 
 Redux is a common package used for maintaining state data in front-end web applications. To allow packages to also use [Redux](https://redux.js.org/) the appui-react package provides the [StateManager]($appui-react) and [ReducerRegistry]($appui-react).  The host app should not create the store itself using the function [createStore](https://redux.js.org/api/createstore) from Redux, but should instead instantiate a StateManager object passing in the set of reducers needed for its own state.  It should not typically include reducers from packages. The StateManager instance will register with the ReducerRegistry to be informed when a Reducer is added to the registry and it will do the work of combining all Reducers into a single Redux store.
 
-See example [StateManager](./framework/State.md/#example-of-defining-initial-set-of-reducers)
+See example [StateManager](./appui/appui‑react/State.md#Example‑of‑Defining‑Initial‑Set‑of‑Reducers)
 
 ## Building UI using Modular Packages
 
 Any package can provide a class that implements the UiItemsProvider interfaces to add UI items to the host application by registering its UiItemsProvider(s) when it is initialized. Items provided at runtime may be inserted into a Toolbar, StatusBar, Backstage or Widget Panel.
 
-See example [UiItemsProvider](./abstract/uiitemsprovider/#uiitemsprovider-example) implementation.
+See example [UiItemsProvider](./abstract/UiItemsProvider.md#UiItemsProvider‑Example) implementation.
 
 UI item definitions for Toolbars, Status Bar, and Backstage specify an item priority value. This value is used to order the items in the parent container. It is suggested that an increment of 10 is used between items in the host application. This provides the opportunity for packages to insert their items adjacent to host application items.
 
@@ -66,16 +66,17 @@ Both the original item definitions, like ToolItemDef and the newer ToolbarItems
   }
 ```
 
-The isHidden property above is specified as a [ConditionalBooleanValue]($appui-abstract) where it evaluates to true if the active view does not support camera usage. For more information on SyncUiEvents see [SyncUi](./framework/syncui/).
+The isHidden property above is specified as a [ConditionalBooleanValue]($appui-abstract) where it evaluates to true if the active view does not support camera usage. For more information on SyncUiEvents see [SyncUi](./appui/appui‑react/Syncui).
 
 ## StatusBar
 
 To ensure that packages can add items to the status bar the [StatusBarWidgetControl]($appui-react) must return the
-[StatusBarComposer]($appui-react) from the getReactNode method. Here is an [example](./framework/statusbar/) of defining a status bar.  Each status bar item definition specifies its position in the status bar using item priority and StatusBarSection.
+[StatusBarComposer]($app
+ui-react) from the getReactNode method. Here is an [example](./appui/appui‑react/StatusBar) of defining a status bar.  Each status bar item definition specifies its position in the status bar using item priority and StatusBarSection.
 
 ## Backstage
 
-The Backstage is a menu used to open frontstages and launch commands. It can also open full-screen overlays, or modal stages, presenting application settings and data management to the user. Applications and packages supply Backstage items definition that are combined by the [BackstageComposer]($appui-react) component to generate the Backstage menu. The Backstage menu is passed as props to the ConfigurableUiContent which is in charge of managing the display of frontstages. Here is an [example](./framework/backstage/#defining-the-backstage) of how applications typically define their backstage.
+The Backstage is a menu used to open frontstages and launch commands. It can also open full-screen overlays, or modal stages, presenting application settings and data management to the user. Applications and packages supply Backstage items definition that are combined by the [BackstageComposer]($appui-react) component to generate the Backstage menu. The Backstage menu is passed as props to the ConfigurableUiContent which is in charge of managing the display of frontstages. Here is an [example](./appui/appui‑react/Backstage.md#Defining‑the‑Backstage) of how applications typically define their backstage.
 
 ## Selection Context Tools
 

docs/learning/ui/QuickStartUi.md

@@ -10,10 +10,10 @@ Full instructions for creating a Web Viewer using create-react-app can be found
 
 ## Modify the basic Frontstage
 
-iTwin's App UI organizes functionality into [Frontstages](./framework/Frontstages.md). Because the iTwin Viewer template for create-react-app provides a basic Frontstage, the quickest way to get started with a new app is to add your app's UI to that Frontstage with the [UiItemsProvider](./abstract/UiItemsProvider.md). This will add you tool buttons, [StatusBar](./framework/StatusBar.md) items, [Backstage](./framework/Backstage.md) items, and [Widgets](./framework/Widgets.md) to the basic viewer when the application loads.
+iTwin's App UI organizes functionality into [Frontstages](./appui/appui‑react/Frontstages.md). Because the iTwin Viewer template for create-react-app provides a basic Frontstage, the quickest way to get started with a new app is to add your app's UI to that Frontstage with the [UiItemsProvider](./abstract/UiItemsProvider.md). This will add you tool buttons, [StatusBar](./appui/appui‑react/StatusBar.md) items, [Backstage](./appui/appui‑react/Backstage.md) items, and [Widgets](./appui/appui‑react/Widgets.md) to the basic viewer when the application loads.
 
 A more detailed explanation of using the UiItemsProvider interface can be found here: [Augmenting the UI of an iTwin App](./AugmentingUI.md).
 
 ## Building a new Frontstage
 
-If you find that you need to make more drastic modifications to the delivered Frontstage, you may need to create a new Frontstage. This [Frontstage](./framework/Frontstages.md) sample can be used as a template for your app's Frontstage. From there, the new Frontstage can be added to your App at startup using a FrontstageProvider. Details in [Adding a Frontstage](./AugmentingUI.md#Adding-a-Frontstage).
+If you find that you need to make more drastic modifications to the delivered Frontstage, you may need to create a new Frontstage. This [Frontstage](./appui/appui‑react/Frontstages.md) sample can be used as a template for your app's Frontstage. From there, the new Frontstage can be added to your App at startup using a FrontstageProvider. Details in [Adding a Frontstage](./AugmentingUI.md#Adding-a-Frontstage).

docs/learning/ui/abstract/Backstage.md

@@ -20,7 +20,7 @@ BackstageItemUtilities.createActionItem("SampleApp.settings", 300, 10, () => Fro
 
 In both examples, the first parameter is a key for the backstage item. This key must be unique across all other backstage items. The next two parameters define the group priority and the item priority within the group.  These values are use to determine the order of the item in the menu. This method allows other packages and extensions to insert items at specific positions within the menu.  It is recommended that the host application increment group priority by 100 and item priority by 10 to provide sufficient gaps for additional groups and items. The ordering is done from lowest to highest priority values.
 
-See additional example in [Backstage](../../../learning/ui/framework/Backstage.md).
+See additional example in [Backstage](../../../learning/ui/appui/appui‑react/Backstage.md).
 
 ## API Reference
 

docs/learning/ui/framework/ChildWindows.md → docs/learning/ui/appui/appui-react/ChildWindows.md

@@ -56,7 +56,7 @@ Careful consideration must be taken when building components for use in a child
 
 ## Widgets
 
-A Widget can specify set its `canPopout` property to true if its supports being in a child window. This allows a Widget to be "popped-out" to its own window and then re-docked in the Widget Panel when the child window is closed. See [Popout Widget Support]($docs/learning/ui/framework/Widgets.md#popout-widget-support) for more details.
+A Widget can specify set its `canPopout` property to true if its supports being in a child window. This allows a Widget to be "popped-out" to its own window and then re-docked in the Widget Panel when the child window is closed. See [Popout Widget Support]($docs/learning/ui/appui/appui‑react/Widgets.md#popout-widget-support) for more details.
 
 ## API Reference
 

docs/learning/ui/appui/index.md

@@ -0,0 +1,35 @@
+# AppUi
+
+## Overview
+
+AppUi refers to an API and a set of components that enable iTwin.js apps to implement iTwin UI's App UI design. This design organizes the [iModel](../../iModels) data into various components on the screen. Graphical data is usually displayed in a [Viewport](../imodel‑components/Viewport), while information such as element properties and data hierarchies are displayed in [Widgets](./appui‑react/Widgets). An app using the App UI design will have a look similar to this:
+
+![AppUi](./images/AppUiDarkTheme.png)
+
+The layout of an AppUi app has the following features:
+
+[Tool Settings](./appui‑react/ToolSettings): a container for any components that change the operational settings of the currently executing [Tool](../../frontend/Tools). These settings are, by default, displayed in a bar at the top of the window:
+
+![ToolSettings](./images/ToolSettings.png)
+
+[Status Bar](./appui‑react/StatusBar): a container that displays notifications, messages from the app, and any feedback from the currently executing Tool. The Status Bar displays as a footer at the bottom of the window:
+
+![StatusBar](./images/StatusBar.png)
+
+[Widgets](./appui‑react/Widgets) are containers of relevant feedback and content for the app's user. They can float or be docked into one of the panels surrounding the content area. Here, we see a "Conversations" widget floating, while "Properties," "Categories" and others are docked into the right-hand panel:
+
+![Widgets](./images/AppUiLightTheme.png)
+
+There are two special Widgets that float on top of the Content Area in the upper right and left corners. The [Tool Widget](./appui‑react/Widgets.md##ToolWidget) in the upper left contains buttons used to launch [iTwin.js Tools](../../frontend/Tools) or functions. The [View Navigation Widget](./appui‑react/Widgets.md##NavigationWidget) contains buttons to launch tools that manipulate the active graphic view, such as zoom, pan, and rotate.
+
+## AppUi Components
+
+Details about the components used to implement AppUi apps:
+
+The React components that make up the AppUi interface are in the [appui-react package](./appui‑react/index).
+
+The [imodel-components-react package](../imodel‑components/index) includes components that work with iModel data, but may be used either inside or outside an AppUi.
+
+React components in the [components-react package](../components/index) are complex components used to display and edit properties are hierarchies. They have no direct dependencies on iTwin.js frontend classes and can be used inside or outside AppUi apps.
+
+The [core-react package](../core/index) is made up of simple React components that can be used anywhere you would use React. Components in the Bentley project [iTwin Ui React](https://github.com/iTwin/iTwinUI‑react) are also used in AppUi and can be used anywhere you can use React components.

docs/learning/ui/components/Common.md

@@ -8,7 +8,7 @@ The Common category can be broken down further into the following sections:
 |Common Section|Description
 |-----|-----
 |Images|Various image processing and rendering interfaces and components, including [IImageLoader]($components-react) and [Image]($components-react).
-|Links|Links are supported in the [PropertyRecord]($appui-abstract) displayed by PropertyGrids, Tables and Trees. The [matchLinks]($components-react) function returns a list of links from a text string.
+|Links|Links are supported in the [PropertyRecord]($appui-abstract) displayed by PropertyGrids and Trees. The [matchLinks]($components-react) function returns a list of links from a text string.
 |Selection|Various enums and types related to Table row and Tree node selection
 |Show/Hide| Various classes and interfaces for Table column show/hide, including [ShowHideDialog]($components-react) and [ShowHideMenu]($components-react).