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], 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.

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.