Webority.Ui.Razor 0.108.0

Webority.Ui.Razor

Webority's internal Razor component library — <app-*> tag helpers plus the shared design system, as a Razor Class Library.

Published publicly so dotnet restore needs no private feed. Built for Webority products; no support commitment outside them.

Use

<PackageReference Include="Webority.Ui.Razor" Version="[0.28.0]" />

_ViewImports.cshtml:

@addTagHelper *, Webority.Ui.Razor

Layout: the stylesheet, Bootstrap's script, the shared custom elements (required by the select, autocomplete, multiselect, phone and date-picker components), and the behaviour layer:

<link rel="stylesheet" href="~/_content/Webority.Ui.Razor/css/webority-theme.css" asp-append-version="true" />
<script src="~/_content/Webority.Ui.Razor/js/bootstrap.bundle.min.js" defer asp-append-version="true"></script>
<script src="~/_content/Webority.Ui.Razor/js/ui-elements.global.js" defer asp-append-version="true"></script>
<script src="~/_content/Webority.Ui.Razor/js/webority-ui.js" defer asp-append-version="true"></script>

Put these in <head>. defer starts the downloads at once without holding up the page, and runs the three scripts in this order once the page is parsed: the same moment scripts at the end of <body> would run, so the controls are ready no later than that. asp-append-version adds a hash of each file to its URL, so a browser keeps the files cached until a package upgrade changes them instead of checking on every page.

An inline <script> runs as the page is parsed, before deferred scripts. Page code that calls WUI, WeborityUiElements or bootstrap therefore goes in a DOMContentLoaded handler or its own defer script, which runs after these three.

ui-elements.global.js carries the shared helpers and the common controls. Every other element (kanban, multi-select, phone, the tour and the rest, plus the chart, calendar, rich text, file viewer and chat engines) loads from beside it the first time the page shows one, including in a server-loaded modal or a swapped fragment, so the layout needs nothing more. Page code that calls a method of such an element first awaits WeborityUiElements.whenElementsReady(). Under a nonce policy the loader copies the nonce of ui-elements.global.js onto what it loads.

The package ships Bootstrap's script (the version the theme is built against), and several components need it: <app-tabs> switches panes through data-bs-toggle="tab", and dismissible <app-alert>s and dropdowns use Bootstrap's behaviour too. Without it the markup renders but tabs never switch. Do not also load another copy of Bootstrap's script (a CDN tag or a vendored file): two copies bind every control twice.

A page that renders <app-phone-number-input> or <app-country-select> also links the country flags, which are a separate stylesheet so other pages do not pay for them:

<link rel="stylesheet" href="~/_content/Webority.Ui.Razor/css/webority-flags.css" />

The phone number rules (formatting and validity by country) are not in ui-elements.global.js either: they are large, so they have their own script, ui-phone.global.js. The field writes no script tag: <wui-phone> (from ui-elements.global.js) adds that script the first time a field on the page needs it, beside ui-elements.global.js and with its cache-bust. The layout needs nothing for it, and a phone field in a server-loaded modal fragment works and logs nothing.

<app-file-viewer> is not in ui-elements.global.js: pdf.js is large, so the viewer has its own script, and the tag adds it after the first viewer on a request, once. The layout needs nothing for it. pdf.js's cmaps, standard fonts and wasm decoders ship in this package too, beside that script, where the viewer finds them; asset-base names another folder only if you host them elsewhere:

<app-file-viewer src="/files/contract.pdf" name="Contract.pdf" download="true">
  <app-file-viewer-actions><app-button size="sm">Approve</app-button></app-file-viewer-actions>
</app-file-viewer>

<app-picture> renders a responsive <picture> (AVIF and WebP sources plus an <img> carrying the real width and height) from an image manifest in the web root. The image build script (tools/build-images.mjs in the source repo; it needs sharp) writes the variants beside each JPG or PNG and the manifest at wwwroot/assets/images.manifest.json; copy it to <web head>/tools/ and run node <web head>/tools/build-images.mjs [--force]. Set another manifest path, if needed, with services.Configure<AppPictureOptions>(o => o.ManifestPath = "img/manifest.json").

<app-picture src="/assets/hero/team.jpg" alt="The team" sizes="(min-width: 992px) 50vw, 100vw" class="rounded" />
<app-picture src="/assets/hero/cover.jpg" alt="" loading="eager" fetchpriority="high" />

src must be a key of the manifest. A missing key throws in Development and renders a plain <img> in other environments.

Then:

<app-button variant="primary">Save changes</app-button>

Component catalogue: https://ui-razor.webority.dev