Core.Portal.Chrome

Core.Portal.Chrome contains portal-safe MVC/Razor chrome primitives for product portals.

Owns

• Auth shell and form-alert components.
• Public auth split-shell template for MVC/Razor and Blazor portal hosts.
• Public and app header partials.
• Appearance controls and static chrome assets.
• Legal footer/link models and shared legal footer renderers.
• Product-neutral legal acceptance and public-auth query primitives.
• Product-agnostic account-support view models and partials.

Does Not Own

• Product workflows, navigation trees, route maps, dashboards, tables, page copy, or customer/product behavior.
• Broker-backed sign-in orchestration. Use Core.Portal.SignIn for Core auth broker login.
• Persistence, database, API-controller, worker, database explorer, or product-repo dependencies.
• Product-specific API clients. Any support client in this package must call product-agnostic Core endpoints only and must be optional for consuming hosts.
• Product-specific legal copy, terms/privacy text, pricing, trial length, billing, tenant provisioning, or legal-record persistence.

Consumer Rules

Product portals should consume this package through NuGet package flow. The product host owns branding, route placement, cookie settings, tenant configuration, typed product API clients, smoke tests, and architecture allowlists.

Public Auth Shell

Use PortalPublicAuthShell and PortalPublicAuthPreferences from Blazor hosts, and the _PortalChromePublicAuthWordmark, _PortalChromePublicAuthPreferences, and _PortalChromePublicAuthBrandField partials from MVC or Razor Pages hosts. Link the compiled Core presentation theme, _content/Core.Portal.Chrome/css/portal-auth-shell.css, and _content/Core.Portal.Chrome/js/portal-auth-shell.js, then set product-owned CSS variables for brand gradients or imagery as needed. Core owns the responsive shell, masthead preference controls, Barlow typeface stack, dark-mode token binding through html[data-theme], signed-out dark semantic fallbacks, form spacing, field sizing, field validation behavior, preference handoff hooks, and alert primitives; product hosts own the sign-in form, forgot-password behavior, provider posture, proof credentials, page copy, routes, cookie names, and storage-key overrides.

Public auth forms opt into the shared behavior with data-auth-form. Mark required visible fields with normal HTML validation attributes such as required, type="email", and minlength, and provide localized messages through data-auth-required-message, data-auth-invalid-message, data-auth-min-length-message, and data-auth-match-message. Password confirmation fields can declare data-auth-match-input="<field name>". Submit buttons can declare data-auth-busy-text; buttons marked data-auth-disabled-permanent remain disabled.

When changing language, portals can preserve non-sensitive state by placing data-auth-preserve-param="<query parameter>" on fields such as email, step, or return URL. Do not mark passwords for preservation.

Cookie-backed Razor Pages hosts should provide PublicLanguageCookieName; the shared script writes the cookie and removes the transient language query parameter on reload. Query-backed Blazor hosts can omit PublicLanguageCookieName; the shared script writes the selected language into LanguageQueryParameterName while preserving marked auth state. The language selector is part of the standard auth shell and defaults to en-US; portals that expose profile or settings language preferences can read CorePortalAuthShell.getPreferences() or consume CorePortalAuthShell.readAuthPreferenceHandoff() after sign-in, then call CorePortalAuthShell.clearAuthPreferenceHandoff() once the product-owned preference store is updated.

Authenticated App Shell

Use PortalAppShell for Blazor portal chrome after sign-in. Link _content/Core.Portal.Chrome/css/portal-app-shell.css, then pass product-owned PortalShellBrandModel, navigation groups, breadcrumbs, search entries, account links, notification rows, to-do rows, optional chat rows, and a theme-toggle callback. Core owns the left context sidebar, collapsible navigation groups, topbar breadcrumb placement, inline search surface, activity buttons with unread badges, right-side activity slideouts with mode titles for Notifications, To Do, and optional Chat, account menu, account-menu light/dark control, and app-shell spacing; product portals own route catalogs, search data, activity data sources, account/tenant identity, authorization, and durable preference persistence. This keeps Transform, Timbertop, WasteWhere, and future portals on one chrome implementation without moving product data or workflow authority into Core.

Hydrating from an identity-backed profile

Appearance and accessibility preferences (theme, text scale, density, display timezone, language) are per-user, not per-tenant (Portal Application Standard preference-scoping ruling, 2026-07-04). The durable store is the platform user profile (GET/PUT /api/core/users/{uid}/preferences, UserPreferencesApiClient); local storage is only a pre-auth/anti-flash cache. After sign-in, a product shell fetches the profile with the typed client and calls CorePortalAuthShell.applyProfilePreferences({ theme, textScale, density, timeZone, uiLocale }) to write those values into the local cache and html[data-theme]/data-text-scale/data-density/data-time-zone/data-ui-locale, making the profile the source of truth. getPreferences() returns the current cached values plus the resolved storage keys (themeStorageKey, textScaleStorageKey, densityStorageKey, timeZoneStorageKey, localeStorageKey) so a shell can read a still-unmigrated local value once and push it up to the profile. Storage keys default to core.portal.* and are overridable through the [data-portal-auth-preferences] data-* attributes so each product can point the seam at its own cache keys.

The public-auth validation standard is:

• client-correctable input (required fields, email format, password length, password confirmation mismatch) uses field-level validation and keeps the primary submit button disabled until valid;
• auth, provider, reset-token, and upstream/server failures use visible alert banners above the form;
• product controllers must return equivalent field-level errors for crafted or no-script POSTs rather than converting missing/malformed values into authentication failures.

Legal Footer And Signup Consent

Use PortalLegalFooterModel with the PortalLegalFooter Blazor component or the _PortalChromeLegalFooter Razor partial to render Terms, Privacy, copyright, and version links in a consistent public-auth footer. Product repos own the legal page routes, localized text, versions, and footer link labels; Core owns only the rendering shape and separator behavior.

Use PortalLegalAcceptanceModel as the product-neutral shape for signup consent evidence when a product needs to map its own trial/customer/signup record into a shared UI or API-adjacent contract. Product repos remain responsible for requiring consent at the correct workflow point, storing the record, and displaying it in customer/subscription admin surfaces.

Use PortalPublicAuthQuery.BuildPasswordStepPath and PortalPublicAuthQuery.ResolveEmailAddress for email-first auth handoffs. New visible URLs should use emailAddress; username is retained only as a compatibility fallback for existing form posts or old links. Public sign-in pages should ask for email first, then route to the password, SSO, or linked-provider step resolved for that address. Optional PIN access appears as a separate or option on the same sign-in page when a portal supports view-only PINs. Social/external providers render as full-width provider buttons using the shared .login-provider-list and .login-provider-button classes.