Support for hierarchical nested components

[Arlodotexe]

Background

@Arlodotexe thoughts on how hard it'd be to group things in the TOC under 'Controls' that have the Controls package/project name? I think that'd help reduce some of the noise in the TOC and make things easier to find?

@michael-hawker Right now we're just iterating each of our components in the ./components directory to build the list. We still need to create a meta-package for Controls (see https://github.com/CommunityToolkit/Windows/issues/115) but our infrastructure doesn't have an elegant way to account for toolkit-using-toolkit in general, a problem tangential to why we can't do nested components like ./components/Controls/Primitives/ or ./components/AppServices/AppServices.SourceGenerators/.

Our flattened ./components/ folder structure is our "component registry", while our tooling (build scripts, msbuild, props files, etc) strings components together based on that flat list.

Yes, it would be good to group things more here. But if we do that grouping here, it won't be a reflection of how things are actually structured in the toolkit and will be more work to migrate later, after the above work that we'll need to do anyway.

For now, I think it would be preferable to publish docs with the improvements we have here and come back when we've made improvements to our underlying infrastructure (including new redirects that would entail). It will be less confusing for contributors and people consuming our packages.

Originally posted by @Arlodotexe in https://github.com/CommunityToolkit/Tooling-Windows-Submodule/issues/177#issuecomment-2025761892

How it currently works

• Each of our separate components are represented by a separate folder in the tooling/../components directory of the repo consuming our submodule.
• In scenarios where the toolkit needs to reference another toolkit component, we:
  • Hardcode the absolute path in Directory.Build.props.
  • Reference the variables defined in Directory.Build.props via a hardcoded ProjectReference in the component's source project.

Problem

1. Our infrastructure only supports a flat list of components in the ./components/ directory.
2. Even with a flat list, our infrastructure doesn't have an elegant way to account for toolkit-using-toolkit.

This has a few effects:

• Added difficulty when a component needs to reference another, especially if it hasn't been set up already
• Flat list makes it difficult to create and manage "meta-packages", which are crucial for consumers to quickly install sets of their favorites parts of the toolkit, particularly our various Controls (see https://github.com/CommunityToolkit/Windows/issues/115).

Additionally, building with a ProjectReference shouldn't cause issues when all are built and packaged at the same time/version. However, we've encountered issues with packaging from the platform side, and from the details at hand, it seems like this may be solved by using PackageReference instead. This would be a cleaner solution than detecting when the workaround is needed and auto-applying it.

Solution

• The improved component system should allow components to add toolkit references via their ToolkitComponentName.
• Each component folder needs a new way of being identified, which can be discussed here.
  • I suggest that rather than building a manifest file, we use the existing information we have.
  • The source project is the minimum requirement for a toolkit component (tests and samples are optional), and it already contains all the information needed to identify the component, including a ToolkitComponentName, which is always the same as the component folder name.
  • We can use this to identify when an src folder is a toolkit source component, allowing us to identify when the parent folder is a full component that may contain tests and samples.
  • This allows us to recursively crawl the folder structure and build a nested hierarchy
• This should be an msbuild target or task which, given a ToolkitComponentName, finds the csproj recursively (similarly to what we're doing in CheckMultiTargets.props) and adds a ProjectReference or PackageReference to the toolkit component..