AIFACTORY-FEAT-168: Blazor microfrontend library template: AppShell chrome, a neutral exemplar and a generated-solution gate¶
Generated from the architecture model
This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic Ecosystem component extensions · Increment I3 Studio · State elaborated · Route frontend-developer · Phase before development · Build order 32 of 185 (Templates and libraries)
Before development
Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I3 are developed. The mark travels with every task (tag phase:before-development).
The Studio microfrontends are scaffolded from the microfrontend library template. Its own F11 record logs the gaps left open: the sample chrome is a custom navigation instead of the UIKit AppShell and still uses raw Tailwind colours instead of the cs-* semantic tokens, the sample microfrontends are Identity teaching stubs, the build has no MAX_PATH redirect, and the epic-level acceptance of the template (install, generate every parameter combination, build, run) is still unchecked. Component: Blazor Shell + MFEs + UIKit (extend).
| Delivers | — |
| Stubs | — |
| Realizes | components: cmp-blazor-shell adrs: ADR-0007 |
| Requirements | — |
| Depends on | AIFACTORY-FEAT-167 Blazor shell template: gateway adapters, filter diagnostics and pinned packages before the Studio |
| Sources | model/components.yaml, ConnectSoft.Blazor.MicrofrontendLibraryTemplate/docs/F11-microfrontend-library.md, ConnectSoft.Blazor.MicrofrontendLibraryTemplate/docs/EPIC-PLANNING.md |
AIFACTORY-US-323: Blazor microfrontend library template: the generated shell host renders the UIKit AppShell bound to the shell abstractions, and its chrome uses only the cs-* tokens¶
enabling · persona asset-maintainer
As an asset maintainer, I want the shell host of the microfrontend library template to use the same chrome as the standalone shell template, so that a Studio microfrontend is developed inside the chrome it will be composed into.
The F11 record of the template lists its chrome as a gap: the layout of the core project and its stylesheet are a custom header and navigation, not the UIKit AppShell, and the sample chrome still uses raw Tailwind gray-* and dark: utilities and legacy classes instead of the cs-* semantic tokens; the record leaves the migration as a follow-up. The manual compose matrix of its integration checklist still has two unchecked items: light and dark themes without raw colour regressions, and a mirrored navigation in right-to-left direction. The standalone shell template already renders the AppShell with its regions A to E bound to the shell abstractions. A microfrontend developed in one chrome and composed into another is reviewed twice, so this PBI moves the generated shell host of the library onto the same chrome. The layout of the core project renders the AppShell regions bound to the shell abstractions as the standalone shell template does, with the navigation taken from the microfrontend registry through the navigation filter. The layout and the stylesheet hold no raw gray-* utility, no dark: variant and no legacy class; colour, spacing, type and radius come from the cs-* tokens, so the theme, density and enableRTL parameters of the template switch the chrome through the tokens and the direction attribute. The Gallery sample stays the minimal stub the record describes. The record and the integration checklist mark the two gaps and the two matrix items as closed.
Acceptance criteria
| AC1 | Given a solution generated from the template, when its shell host renders, then the layout of the core project is the UIKit AppShell with its regions bound to the shell abstractions and its navigation comes from the registry through the navigation filter, as in a shell generated from the standalone shell template (ADR-0007: the modules share a common design system and auth context; model/templates.yaml lists both templates). |
| AC2 | Given the layout and the stylesheet of the core project, when the token test scans them, then it finds no raw gray-* utility, no dark: variant and no legacy class, and a planted raw utility fails the test with the file and the class named (ADR-0007, model/components.yaml names the AppShell chrome as a need of this component). |
| AC3 | Given solutions generated with theme Light and Dark, with each density value and with enableRTL on, when the chrome renders, then theme and density change through the tokens only and the navigation is mirrored in right-to-left direction with no clipped text (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml lists the three parameters). |
| Traces: adrs | ADR-0007 |
| Depends on | feature:component-blazor-shell-template-studio, feature:component-uikit-factory-compositions |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-613 Sample chrome on the UIKit AppShell with cs-* tokens |
implementation | The generated shell host of the library renders the UIKit AppShell regions A to E bound to the shell abstractions, as the standalone shell template does; no raw gray-* utility, dark: variant or legacy class remains in the core layout and its stylesheet; theme, density and direction switch through the tokens; the F11 record and the integration checklist mark the chrome gaps as closed. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1388 Token scan test and chrome component tests of the core layout |
fixture | The unit test project holds a scan test over the core layout and its stylesheet that fails on a raw gray-* utility, a dark: variant or a legacy class with the file named, and component tests that render the chrome for both themes, the three density values and right-to-left direction. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1389 Verify the AppShell chrome, the token scan and the theme, density and direction cases |
verification | Generate solutions for the theme, density and direction values and run the tests of AIFACTORY-TASK-1388; the chrome is the AppShell, the scan is clean and fails on a planted utility, which proves AC1 to AC3 of AIFACTORY-US-323 (ADR-0007). | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-US-324: Blazor microfrontend library template: one neutral exemplar microfrontend replaces the Identity teaching stubs and shows the contract a Studio microfrontend follows¶
enabling · persona asset-maintainer
As an asset maintainer, I want the microfrontend the template generates to be a neutral example of the composition contract, so that a Studio microfrontend starts from a clean pattern and not from identity screens it must delete.
The template generates two sample microfrontends, an Identity administration one and an Identity self-service one, and its F11 record calls their screens teaching stubs. They carry a product domain the Studio does not have, and the integration checklist warns that the embedded samples and the standalone Identity templates follow two different navigation contracts that must not be mixed in one host. The composition contract itself is small and is documented in the record: a static descriptor with the assembly and the navigation items of the microfrontend, each item with an id, a text, a target, an icon, an optional required policy and an order, and one registration method that owns the dependency injection and the authorization policies of the microfrontend and that the shell calls once. A microfrontend references the shell contracts and the shell service abstractions and never the shell services package. This PBI replaces the two Identity stubs in the generated solution by one neutral exemplar microfrontend that carries no product domain. It has a descriptor, two navigation items of which one requires a policy, the registration method, one page that reads the scope and the user from the shell abstractions and one page that shows the loading, empty and error states with the kit components, and component tests for both. The registry, the host wiring, the contract tests and the scaffold test of the template follow the exemplar. Two parameters were meant for the Identity samples and gate nothing: IncludeSampleData is a symbol definition without a use, and UseLocalDb appears only in a conditional whose branches change no generated file; the parameter snapshot of this repository already binds UseLocalDb to false because a microfrontend holds no database. With the samples gone both are removed from the template configuration and its host files, and a scaffold test keeps the rule that every remaining parameter changes at least one generated file. The standalone Identity sample templates are other repositories and stay as they are. The record, the sample notes and the checklist describe the exemplar as the pattern.
Acceptance criteria
| AC1 | Given a solution generated from the template, when its projects are listed, then it holds one exemplar microfrontend project and no Identity sample project, the exemplar has a descriptor with its assembly and two navigation items and one registration method, and the shell host composes it through the registry (ADR-0007: each module of the Studio is a microfrontend composed into the shell; model/templates.yaml row of connectsoft-blazor-mfe). |
| AC2 | Given the exemplar project, when the architecture tests run, then it references the shell contracts and the shell service abstractions only, a planted reference to the shell services package fails the test, and no type or route of the exemplar names a product domain (ADR-0007, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md). |
| AC3 | Given the generated solution, when its tests run, then the component tests of the two exemplar pages pass, the item that requires a policy is hidden from a user without it, and the contract tests assert the ids, targets and unique orders of the exemplar navigation (ADR-0007, model/components.yaml names the neutral exemplar as a need of this component). |
| AC4 | Given the template configuration after this PBI, when the parameter-effect test generates a solution per value of every parameter, then every parameter changes at least one generated file, UseLocalDb and IncludeSampleData are defined in no configuration or host file of the template, and a planted parameter that gates nothing fails the test by name; the next inventory drops both from model/template-parameters/connectsoft-blazor-mfe.yaml (ADR-0007). |
| Traces: adrs | ADR-0007 |
| Depends on | AIFACTORY-US-323 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-614 Neutral exemplar microfrontend with its descriptor and navigation contribution |
contract | One neutral exemplar microfrontend with its descriptor, its navigation contribution, the {X}Mfe and Add{X}Mfe pair, two pages and component tests shows the contract a Studio microfrontend follows; the exemplar carries no product domain and references the shell contracts and abstractions only. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1390 Identity teaching stubs removed and the host, registry and tests moved to the exemplar |
implementation | The two Identity sample projects leave the template and the solution; the registry, the host wiring, the contract tests, the coverage tests and the scaffold test that asserted both Identity microfrontends assert the exemplar; the template configuration and the nuspec name no removed project. | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1427 Dead parameters UseLocalDb and IncludeSampleData removed and a parameter-effect test added |
contract | The template configuration, dotnetcli.host.json and ide.host.json of the template no longer define UseLocalDb and IncludeSampleData, and the conditional on UseLocalDb whose branches change nothing is gone; the scaffold test project holds a parameter-effect test that generates a solution per value of every parameter and fails with the parameter named when a parameter changes no generated file; the removal is noted for the next inventory of model/template-parameters/connectsoft-blazor-mfe.yaml. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1391 F11 record, sample notes and integration checklist describe the exemplar |
documentation | The F11 record, the sample notes of the source folder, the Architecture page and the integration validation checklist of the template describe the exemplar as the composition pattern, drop the embedded Identity routes and keep the note that the standalone Identity templates are separate. | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1392 Verify the exemplar contract, the reference rule and the navigation tests |
verification | Generate a solution, build and test it, plant a reference to the shell services package in the exemplar and plant a parameter that gates nothing; the solution holds the exemplar only, its tests pass, the planted reference fails the architecture test and the planted parameter fails the parameter-effect test, which proves AC1 to AC4 of AIFACTORY-US-324 (ADR-0007). | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-US-325: Blazor microfrontend library template: a generated solution shortens its intermediate and output roots so that long nested paths build on Windows¶
enabling · persona asset-maintainer
As an asset maintainer, I want a solution generated from the template to build under a long repository path on Windows, so that a Studio repository with long project names does not fail on the path length limit.
The F11 record of the template states that its build properties file is present but holds no redirect of the intermediate output path, unlike the administration microfrontend templates of the SaaS family, which shorten their intermediate and output roots for the Windows path limit; the record leaves the redirect as a follow-up to adopt when a build hits the limit. The repositories of the Factory carry long names, and a solution generated under such a name nests the project name several times inside its intermediate folders, so the Studio is the case the record anticipated. This PBI adopts the redirect. The build properties file of a generated solution sets short roots for the intermediate and the output folders of the source, test and sample projects, in the style the record points at, and the ignore file, the test settings and the pipeline of the generated solution follow the new roots. The redirect changes no assembly name and no package content. A generation under a root path near the limit, with a solution name of the length of a Factory repository name, restores, builds and tests on a Windows agent. The record marks the gap as closed and names the roots.
Acceptance criteria
| AC1 | Given a solution generated under a deep root path with a name as long as a Factory repository name, when it is restored, built in Release and tested on a Windows agent, then no step fails on the path length limit (ADR-0007; model/components.yaml names the generated-solution gate of this template, which this case joins). |
| AC2 | Given a generated solution with the short roots, when its package content and assembly names are compared with those of a solution built without the redirect, then they are equal, and the ignore file and the pipeline of the generated solution name the new roots (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml gains no parameter by this PBI). |
| Traces: adrs | ADR-0007 |
| Sources | model/components.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1393 Short intermediate and output roots in the build properties of a generated solution |
implementation | The build properties file of a generated solution redirects the intermediate and the output folders of its source, test and sample projects to short roots; the ignore file, the test settings and the pipeline follow them; the F11 record names the roots and marks the gap as closed. | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1394 Verify a deep-path generation on a Windows agent |
verification | Generate a solution with a long name under a deep root on a Windows agent, restore, build and test it, and compare its package content with a build without the redirect; no path error occurs and the content is equal, which proves AC1 and AC2 of AIFACTORY-US-325. | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-US-326: Blazor microfrontend library template: the packed template is installed, generated across its documented parameters, built, tested and started before the package publishes¶
evidence · persona asset-maintainer
As an asset maintainer, I want every change of the microfrontend library template to be gated by the solutions it generates from the packed candidate, so that a package that would scaffold a solution that does not build or start never reaches the feed.
This PBI is the gate of the feature. The planning page of the template keeps its epic-level acceptance unchecked: the template installs, generates a complete solution that builds, the generated solution runs with its shell and microfrontends, the UI kit works with all three adapters, every parameter is functional and the pipelines are tested. The installer pipeline file of the template only calls the shared installer job of ConnectSoft.AzurePipelines, whose steps pack, validate one instantiation and push in one sequence, and the scaffold test project of the repository covers one composed solution. A gate between pack and push and a refusal of a repeated version are changes of the shared steps: the gate hook and the version guard that AIFACTORY-TASK-1426 of the feature component-base-template-findings adds, the guard being opt-in. This template switches the hook on and defines its cases, which turn the acceptance list into cases of the pipeline. The candidate is packed once and installed. The scaffold tests instantiate it across the parameters that gate generated files: uiKitAdapter in its three values, theme, density, enableRTL, includeTests and EnableHttps, reduced to the pairs of values so that the run stays bounded while every pair is covered, and the deep-path case on a Windows agent. The two dead parameters AIFACTORY-US-324 removes are not part of the matrix, and its parameter-effect test is what proves the line that every parameter is functional. Each output is restored, built in Release and tested; its host is started and the home route and the route of the exemplar are probed; the output is scanned for template placeholders that were not replaced. A case that fails any stage fails the run with the parameter values and the stage named, and the push is not reached. Publication pushes the package to the ConnectSoft feed with a version that is not yet on the feed. The template gains no Factory profile, so no additional profile case is declared. The planning page marks its acceptance by the cases that prove it. This is an evidence PBI: a template feature has no scenario, so the gate names what it proves through traces.adrs and its sources.
Acceptance criteria
| AC1 | Given a change of the template, when its installer pipeline runs, then the candidate is packed once and installed, the gate hook of the shared installer steps runs the scaffold cases across the pairwise matrix of uiKitAdapter, theme, density, enableRTL, includeTests and EnableHttps and for the deep-path case, and each output is restored, built in Release, tested, started, probed on the home route and the exemplar route and scanned (ADR-0007; model/template-parameters/connectsoft-blazor-mfe.yaml lists the parameters of the matrix). |
| AC2 | Given a case fails any stage, when the pipeline evaluates the run, then the run fails with the parameter values and the stage named, no later stage of that case is reported as passed and the publication stage is not reached; a fixture with a planted failing case proves the refusal (ADR-0007, model/backlog/epics.yaml states the gate as the completion of the epic). |
| AC3 | Given every case is green, when the push step runs, then the package is pushed to the ConnectSoft feed with a version that is not on the feed, the version guard of the shared installer steps refuses a repeated version with the reason, and the planning page of the template marks each line of its epic-level acceptance by the case that proves it, the line on functional parameters by the parameter-effect test of AIFACTORY-US-324 (ADR-0007, docs/architecture/catalogs/templates.md keeps the row of the template). |
| Traces: adrs | ADR-0007 |
| Depends on | AIFACTORY-US-323, AIFACTORY-US-324, AIFACTORY-US-325, feature:component-blazor-shell-template-studio, feature:component-base-template-findings |
| Sources | model/components.yaml, model/backlog/epics.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0007-blazor-mfe-studio-frontend.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1395 Parameter matrix of the scaffold tests passed to the gate hook of the shared installer steps |
operations | The scaffold test project defines the pairwise matrix of uiKitAdapter, theme, density, enableRTL, includeTests and EnableHttps and the deep-path case, each case restoring, building, testing, starting and probing its output; the installer pipeline file of the template switches on the gate hook of the shared installer steps, delivered by AIFACTORY-TASK-1426 of the feature component-base-template-findings, passes it these cases and sets no allowPackageConflicts; the planning page maps each acceptance line to its case. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-1396 Planted failing case fixture for the gate |
fixture | A pipeline fixture generates one case whose exemplar route is not registered and asserts that the run fails at the probe stage with the parameter values named and that the publication stage is not reached. | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-615 Generated-solution gate and MAX_PATH redirect |
verification | One green run and one planted run of the gate: the pipeline installs the packed template, generates the parameter combinations the template documents and the deep-path case, builds, tests and starts each generated solution and fails when any case fails; the planted case stops the run before publication and the green run publishes the package with a verified version, which proves AC1 to AC3 of AIFACTORY-US-326 (ADR-0007). | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-US-126: Blazor microfrontend library template: AppShell chrome, a neutral exemplar and a generated-solution gate is delivered and proven on a generated solution¶
enabling · persona asset-maintainer
As an asset maintainer, I want Blazor Shell + MFEs + UIKit to carry AppShell chrome, a neutral exemplar and a generated-solution gate, so that it serves Factory Studio and generated product UIs without later rework.
This is the integration PBI of the feature. An asset maintainer packs the microfrontend library template with the AppShell chrome on the cs-* tokens, the neutral exemplar, the short build roots and the aligned pins of the shell family, installs the package and instantiates it across its parameters in the installer pipeline. Every generated solution builds, passes its tests and starts before the package is allowed to publish; a case that fails any stage fails the run and blocks publication. The implementation lives in the earlier PBIs of this file; this PBI proves them together on the solution a Studio microfrontend is developed in. From the published package a solution is generated with the Tokens adapter under a long repository name. Its shell host renders the AppShell with the exemplar in the navigation, the exemplar follows the descriptor pair and references no shell services package, the chrome holds no raw colour utility, and the solution builds on a Windows agent. The feature is done when that solution is generated from a fresh install of the published package. Repository of the feature: ConnectSoft.Blazor.MicrofrontendLibraryTemplate.
Acceptance criteria
| AC1 | Given the template repository ConnectSoft.Blazor.MicrofrontendLibraryTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0007, model/components.yaml). |
| AC2 | Given the work of AIFACTORY-TASK-613 (sample chrome on the UIKit AppShell with cs-* tokens) is done, then the generated shell host of the library renders the UIKit AppShell regions bound to the shell abstractions, as the standalone shell template does, no raw gray-* or dark: utility remains in the core layout and its stylesheet, and theme, density and direction switch through the tokens (ADR-0007, model/template-parameters/connectsoft-blazor-mfe.yaml). |
| AC3 | Given the work of AIFACTORY-TASK-614 (neutral exemplar microfrontend with its descriptor and navigation contribution) is done, then the Identity teaching stubs are replaced by one neutral exemplar microfrontend whose descriptor, navigation contribution, descriptor pair and component tests show the contract a Studio microfrontend follows, and the exemplar carries no product domain (ADR-0007, model/templates.yaml). |
| AC4 | Given the work of AIFACTORY-TASK-615 (generated-solution gate and MAX_PATH redirect) is done, then the pipeline installs the packed template, generates the combinations of the parameters that gate generated files, builds and runs each generated solution and fails when any case fails, and a generated solution shortens its intermediate and output roots so that long nested paths build on Windows (ADR-0007, docs/architecture/catalogs/templates.md). |
| Traces: adrs | ADR-0007 |
| Depends on | AIFACTORY-US-323, AIFACTORY-US-324, AIFACTORY-US-325, AIFACTORY-US-326 |
| Sources | model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-blazor-mfe.yaml, docs/architecture/catalogs/templates.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-1397 Generate a solution from the published package under a long name and start it |
verification | A probe installs the published package, generates a solution with the Tokens adapter under a name of the length of a Factory repository name on a Windows agent, builds and tests it, starts the host and probes the home route and the exemplar route; the run proves AC2 to AC4 of AIFACTORY-US-126 on the published package (ADR-0007). | ConnectSoft.Blazor.MicrofrontendLibraryTemplate |
AIFACTORY-TASK-675 Verify blazor-mfe-library-template-delivered by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every generated case after the published package is installed; they pass and prove AC1 to AC4 of AIFACTORY-US-126. |
ConnectSoft.Blazor.MicrofrontendLibraryTemplate |