From 46ce627ea51937c703c441b5a5c3e67341001539 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Mon, 1 Jun 2026 05:05:26 -0400 Subject: [PATCH] docs(theme): RCL README + verified pack MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Full Release build (0 warnings, TreatWarningsAsErrors), 32/32 bUnit tests green. Pack confirmed: staticwebassets/css/theme.css, staticwebassets/css/layout.css, and the three IBM Plex woff2 fonts ship in ZB.MOM.WW.Theme.0.1.0.nupkg. README covers the one-paragraph intro, 3-step Adopt guide, thin-MainLayout→ThemeShell delegation example, component/enum reference table, static-asset paths, and build commands. --- ZB.MOM.WW.Theme/README.md | 93 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 ZB.MOM.WW.Theme/README.md diff --git a/ZB.MOM.WW.Theme/README.md b/ZB.MOM.WW.Theme/README.md new file mode 100644 index 0000000..da25a9f --- /dev/null +++ b/ZB.MOM.WW.Theme/README.md @@ -0,0 +1,93 @@ +# ZB.MOM.WW.Theme + +Shared Technical-Light UI kit for the ZB.MOM.WW SCADA family: design tokens + IBM Plex +fonts (static web assets) and a canonical side-rail shell + widgets. The kit ships one +.NET 10 Razor Class Library (RCL) with CSS custom-property tokens, the three IBM Plex +woff2 fonts, and side-rail layout CSS — all served from `_content/ZB.MOM.WW.Theme/…` — +plus a set of Blazor SSR components that carry no inline colours and reuse the token +classes. Bootstrap 5 is **not** vendored; each app keeps its own Bootstrap link. + +## Adopt + +1. Reference the NuGet package in your app; keep your own Bootstrap 5 `` in `App.razor`. +2. In `App.razor` ``, **after** your Bootstrap link, add ``: + ```razor + @* Bootstrap — yours, not vendored by the kit *@ + + ``` +3. Make your `MainLayout` a thin delegate to `ThemeShell` — `@layout` cannot pass + parameters, so `ThemeShell` is a regular component and `MainLayout` is a 3-line wrapper: + + ```razor + @* Layouts/MainLayout.razor *@ + @inherits LayoutComponentBase + + + @* session info / sign-out link *@ + @Body + + ``` + +Add `@using ZB.MOM.WW.Theme` to your `_Imports.razor` so all components are available +without per-file usings. + +### Login page + +Use `` for the sign-in form. The card posts to a server endpoint +(`/auth/login` by default) so `SignInAsync` can run before the response starts. +You **must** inject `` inside the card and **validate `ReturnUrl` +server-side** before redirecting (open-redirect risk): + +```razor + + + +``` + +## Components + +| Component | Parameters (key) | Notes | +|---|---|---| +| `ThemeHead` | — | Emits `` tags for `theme.css` and `layout.css`. Place in `` after Bootstrap. | +| `ThemeShell` | `Product`*, `Accent`, `Logo`, `Nav`, `RailFooter`, `ChildContent` | Side-rail chassis. Not a layout — delegated to from `MainLayout`. `Accent` overrides `--accent` token. | +| `BrandBar` | `Product`*, `Logo` | Brand glyph + product name; rendered inside `ThemeShell`'s rail header. | +| `NavRailItem` | `Href`*, `Text`*, `Icon`, `Match` | Wraps ``. | +| `NavRailSection` | `Title`*, `Expanded` (default `true`), `ChildContent` | CSS-only collapsible `
` group; no JS, works in static SSR. | +| `StatusPill` (`StatusState`) | `State`* (`Ok`/`Warn`/`Bad`/`Idle`/`Info`), `ChildContent` | Inline chip. `StatusState` enum is in `ZB.MOM.WW.Theme`. | +| `LoginCard` | `Product`*, `Action` (default `/auth/login`), `ReturnUrl`, `Error`, `ChildContent` | Static form-POST sign-in card. Inject `` via `ChildContent`; validate `ReturnUrl` server-side. | +| `TechButton` (`ButtonVariant`) | `Variant` (`Primary`/`Secondary`/`Danger`/`Ghost`), `Type`, `Busy`, `ChildContent`, splatted attrs | `Busy` disables the button and shows a spinner. `ButtonVariant` enum is in `ZB.MOM.WW.Theme`. | +| `TechCard` | `Title`, `Header`, `ChildContent`, `Footer`, `Class` | Panel with optional head/body/footer slots. | +| `TechField` | `Label`*, `Hint`, `Error`, `ChildContent` | Form field wrapper with label, hint text, and inline error. | + +\* `EditorRequired` parameter. + +Flat namespace: all components and enums live in `ZB.MOM.WW.Theme`. One `@using` covers everything. + +## Static assets + +Served at `_content/ZB.MOM.WW.Theme/…` by the ASP.NET static-web-asset pipeline: + +| Path | Contents | +|---|---| +| `css/theme.css` | Design tokens (`--accent`, `--ok`, `--warn`, …), typography, utility helpers | +| `css/layout.css` | Side-rail shell layout, collapsible nav, `StatusPill` variants, card/field helpers | +| `fonts/ibm-plex-sans-400.woff2` | IBM Plex Sans Regular | +| `fonts/ibm-plex-sans-600.woff2` | IBM Plex Sans SemiBold | +| `fonts/ibm-plex-mono-500.woff2` | IBM Plex Mono Medium | + +`theme.css` declares `@font-face` with `url('../fonts/…')` — correct relative path from +`css/` to `fonts/`. (OtOpcUa's original `url('fonts/…')` was a latent 404; the kit fixes it.) + +## Build + +```bash +# from ZB.MOM.WW.Theme/ +dotnet build -c Release # TreatWarningsAsErrors — expect 0 warnings +dotnet test # 32 bUnit tests +./build/pack.sh # → ./artifacts/ZB.MOM.WW.Theme.0.1.0.nupkg +```