feat(theme): implement accessible Technical-Light 1.0 contracts
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user