feat(theme): implement accessible Technical-Light 1.0 contracts

This commit is contained in:
Joseph Doherty
2026-11-13 15:49:08 -05:00
parent 8969bee6a9
commit f8469aa837
63 changed files with 3695 additions and 120 deletions
@@ -1,12 +1,13 @@
# Shared library: `ZB.MOM.WW.Theme`
**Status: Built + Published + Adopted (`0.2.0`).** The RCL lives at
[`scadaproj/ZB.MOM.WW.Theme/`](../../../ZB.MOM.WW.Theme/) — built, tested (44 bUnit tests), and
**published to the Gitea NuGet feed**. **Adopted across all three apps on 2026-06-03** — merged to each repo's
local default and **pushed to origin (gitea)**, in sync (see [`../GAPS.md`](../GAPS.md)).
Realizes [`../spec/SPEC.md`](../spec/SPEC.md).
**Current published release: 0.5.3; accessible candidate: 1.0.0 (not yet published).**
The .NET 10 RCL lives at [`ZB.MOM.WW.Theme`](../../../ZB.MOM.WW.Theme/).
The integrated candidate suite currently passes 105 tests, zero failures/skips;
package canaries and release acceptance remain pending. See [release decision](../RELEASE-DECISION.md)
for exact consumer pins, version policy and scope, and [interaction recipes](../spec/INTERACTION-RECIPES.md)
for host-owned behavior. Realizes [the shared specification](../spec/SPEC.md).
`0.2.0` adds **shared nav-expand persistence**: `NavRailSection` gained a `Key` parameter (emitted as
Historical extraction: `0.2.0` adds **shared nav-expand persistence**: `NavRailSection` gained a `Key` parameter (emitted as
`data-nav-key`, defaulting to a slug of `Title`), a vendored `wwwroot/js/nav-state.js` localStorage enhancer
(keyed by `data-nav-key`, prefix `zbnav:`, idempotent), and a new **`ThemeScripts`** component (sibling to
`ThemeHead`) that emits the enhancer `<script defer>` before `</body>`. This lets every app persist nav
@@ -17,27 +18,29 @@ expand-state from one shared, static-SSR-friendly mechanism (no per-app cookie/J
## Package
One NuGet package — unlike `ZB.MOM.WW.Auth`'s four-package split, there are no
tokens-only or components-only consumers; all three apps consume the full kit.
tokens-only or components-only consumers; Blazor consumers use the full kit; registry/Perspective use the verified static export.
| Package | Target | Notes |
|---|---|---|
| `ZB.MOM.WW.Theme` | `net10.0` Razor Class Library | Tokens + fonts + layout CSS + all components |
Published to the Gitea NuGet feed; `Version 0.2.0`. SemVer — token changes are
breaking (major bump); the `0.1.0 → 0.2.0` bump added nav persistence (`NavRailSection.Key` +
`ThemeScripts` + `nav-state.js`) additively. Build from `scadaproj/ZB.MOM.WW.Theme/`:
Semantic token compatibility is versioned. Build/test/pack from `ZB.MOM.WW.Theme/`:
```bash
dotnet build -c Release # 0 warnings (TreatWarningsAsErrors)
dotnet test # 44 bUnit tests
./build/pack.sh # → ./artifacts/ZB.MOM.WW.Theme.0.2.0.nupkg
GITEA_NUGET_SOURCE=… GITEA_NUGET_KEY=… ./build/push.sh # publish to the Gitea feed
dotnet build ZB.MOM.WW.Theme.slnx -c Release
dotnet test tests/ZB.MOM.WW.Theme.Tests/ZB.MOM.WW.Theme.Tests.csproj -c Release --no-build
./build/pack.sh
```
Publish only the exact reviewed artifact after canaries, independently verify its feed
hash, and never repack or wildcard-push immutable versions. Public-feed-only/native
hosts consume the exact package-derived static export rather than a private dependency.
---
## Consumer matrix
All three apps consume the single RCL. No optional packages.
The adoption matrix in the release decision lists all seven Blazor consumers and native surfaces. There are no optional RCL packages.
| Consumer | Surface | Consumes |
|---|---|---|
@@ -53,7 +56,7 @@ Served at `_content/ZB.MOM.WW.Theme/…` by ASP.NET's static-web-asset pipeline.
| Path | Contents |
|---|---|
| `css/theme.css` | Design tokens, typography, Bootstrap 5 overrides (379 lines) |
| `css/theme.css` | Design tokens, typography, Bootstrap 5 token overrides |
| `css/layout.css` | Side-rail shell layout, collapsible nav CSS, `StatusPill` variants, `TechCard`/`TechField` helpers |
| `fonts/ibm-plex-sans-400.woff2` | IBM Plex Sans Regular — vendored, no CDN |
| `fonts/ibm-plex-sans-600.woff2` | IBM Plex Sans SemiBold — vendored, no CDN |
@@ -96,12 +99,16 @@ state (keyed by its `data-nav-key`) across navigation and reloads; pure client-s
### `ThemeShell`
Canonical side-rail chassis. **Not a `LayoutComponentBase`** — delegated to from the app's
thin `MainLayout`. The `Accent` parameter overrides `--accent` for the shell subtree.
thin `MainLayout`. The complete accent parameter family scopes product states to the shell subtree; omitted values inherit.
| Parameter | Type | Required | Default | Notes |
|---|---|---|---|---|
| `Product` | `string` | Yes | — | Product name rendered in `BrandBar` |
| `Accent` | `string?` | No | `null` | Override `--accent` for this app (e.g. `#2f855a`) |
| `Accent` | `string?` | No | `null` | Primary accent; existing callers supported |
| `AccentDeep` | `string?` | No | `null` | Deep hover/pressed/link text |
| `AccentTint` | `string?` | No | `null` | Selected surface |
| `AccentBorder` | `string?` | No | `null` | Interactive border |
| `AccentFocus` | `string?` | No | `null` | Visible keyboard focus |
| `Logo` | `RenderFragment?` | No | `null` | Custom logo; replaces default `▐` glyph |
| `Nav` | `RenderFragment?` | No | `null` | Rail nav items (`NavRailSection` / `NavRailItem`) |
| `RailFooter` | `RenderFragment?` | No | `null` | Session block / sign-out at rail bottom |
@@ -217,7 +224,10 @@ Themed button wrapping Bootstrap `.btn` classes.
|---|---|---|---|---|
| `Variant` | `ButtonVariant` | No | `Primary` | `Primary`, `Secondary`, `Danger`, `Ghost` |
| `Type` | `string` | No | `"button"` | HTML `type` attribute |
| `Busy` | `bool` | No | `false` | Disables button + shows spinner |
| `Busy` | `bool` | No | `false` | Disables, shows decorative spinner; explicit aria-busy |
| `BusyText` | `string?` | No | `null` | Optional label while busy; original content returns afterward |
| `Size` | `ButtonSize` | No | default | Standard, Small, Large |
| `Class` | `string?` | No | `null` | Merged with required and unmatched classes |
| `ChildContent` | `RenderFragment?` | No | `null` | Button label |
| (splatted) | `IDictionary<string,object>?` | No | — | Passes through arbitrary HTML attributes |
@@ -248,6 +258,9 @@ Labeled form-field wrapper: label, input slot, hint text, and inline error.
| Parameter | Type | Required | Notes |
|---|---|---|---|
| `Label` | `string` | Yes | `<label>` text |
| `For` | `string?` | No | Caller-owned control id |
| `HintId` | `string?` | No | Id on hint only when Hint exists |
| `ErrorId` | `string?` | No | Id on error only when Error exists |
| `Hint` | `string?` | No | Rendered as `.form-text` below the input |
| `Error` | `string?` | No | Rendered as `.field-error.s-bad` below the input |
| `ChildContent` | `RenderFragment?` | No | The `<input>`, `<select>`, or other control |
@@ -259,8 +272,12 @@ Labeled form-field wrapper: label, input slot, hint text, and inline error.
- **Bootstrap is not vendored.** Each app keeps its own Bootstrap `<link>`. The RCL's
`theme.css` overrides `--bs-*` tokens to align Bootstrap with Technical-Light but
does not ship Bootstrap itself.
- **No global JavaScript.** `NavRailSection` is CSS-only (`<details>`). Apps may add
their own `nav-state.js` for interactive expand-state if needed (OtOpcUa has one).
- **Shared optional nav enhancer.** Native disclosure works without JavaScript;
`ThemeScripts` loads shared idempotent `nav-state.js` once for persisted section state.
- **No auth logic.** The RCL is UI-only. Wire `LoginCard` to `ZB.MOM.WW.Auth` endpoints
in the app.
- **No data grids, modals, or domain-specific components.** These stay per-project.
TechField callers own control `aria-describedby`/`aria-invalid` and unique IDs. TechButton
callers own persistent live outcomes; no secret values or polling chatter. See the library README
for migration examples. TreeTable remains a stateless rendering adapter with caller-owned rows.