Solhigson.Admin 10.1.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Solhigson.Admin --version 10.1.0
                    
NuGet\Install-Package Solhigson.Admin -Version 10.1.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Solhigson.Admin" Version="10.1.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Solhigson.Admin" Version="10.1.0" />
                    
Directory.Packages.props
<PackageReference Include="Solhigson.Admin" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Solhigson.Admin --version 10.1.0
                    
#r "nuget: Solhigson.Admin, 10.1.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Solhigson.Admin@10.1.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Solhigson.Admin&version=10.1.0
                    
Install as a Cake Addin
#tool nuget:?package=Solhigson.Admin&version=10.1.0
                    
Install as a Cake Tool

Solhigson.Admin

Admin screens for Solhigson apps, built as Razor components and rendered on the server: static server rendering with enhanced navigation, no interactive mode. It builds on Solhigson.Framework.Core.

An app owns its routes. The package ships no page: every component here is placed by the app, on a page the app declares with its own @page route and its own permission.

The head

KitHead (Solhigson.Admin.Components) links the kit's stylesheets, kit.css first, through Assets[...], so a host that calls app.MapStaticAssets() serves each at its content-specific url. Place it in the app's <head>, before the app's own stylesheets:

<head>
    <KitHead Nonce="@nonce" />
    <link rel="stylesheet" href="@Assets["app.css"]" />
</head>

Nonce is optional. An app whose Content-Security-Policy allows styles or scripts by nonce passes the nonce it generated for this response's CSP header, fresh for each response, never a value read from the request; KitHead puts it on every link and script it emits.

After its stylesheets, KitHead loads the kit's scripts with defer: kit.forms.js, the busy mark under Buttons; kit.theme.js, the switch under Light and dark; kit.dialog.js, which opens and fills the dialogs under Dialogs and confirms; and kit.menu.js, which places the row menus under Row menus.

Tokens

kit.tokens.css states every colour, size, space, radius, shadow, duration and font the kit reads, as --kit-* custom properties on :root; no other kit stylesheet holds a value of its own. The kit's one colour is black: the ink is #000000 and every grey is untinted; the four states (success, warn, danger, info) are its only hues.

Each colour and shadow has a dark value. A page follows the reader's prefers-color-scheme unless it sets data-theme="light" or data-theme="dark" on its <html> element. Every text and state colour meets WCAG contrast 4.5 to 1 on the surfaces it sits on, and the control border and focus ring 3 to 1, in both themes.

The fonts are the reader's system faces; the package ships no font file and links no font host. An app that wants other faces sets --kit-font-sans, --kit-font-serif and --kit-font-mono.

Overriding the kit

kit.css, the first stylesheet KitHead links, names the cascade layers, lowest first: @layer reset, kit.tokens, kit.base, kit.components, app;. KitHead goes before the app's stylesheets, since layer order is set where a layer is first seen. A rule in a later layer beats one in an earlier layer whatever its specificity, so an override in app needs no !important; no kit rule uses !important or an id selector.

An app overrides the kit at three levels, each in its own @layer app:

  1. A global token, such as --kit-ink, set on :root. A token override gives its own dark value, in the two blocks the kit uses: under @media (prefers-color-scheme: dark) on :root:not([data-theme="light"]), and on :root[data-theme="dark"]. Without them your light value stays in dark mode, on the kit's dark surfaces: a layer beats the kit whatever its selector. An app overriding --kit-ink sets --kit-on-ink, the text on it, beside it in each theme, and --kit-ink-hover, a primary button's fill under the pointer; one overriding --kit-state-danger sets --kit-state-danger-hover likewise. The focus ring is black (white in dark) and stays so: an app re-inking the kit decides --kit-focus itself.
  2. A component token, such as --kit-mark-gap or --kit-btn-height, which a component reads before its global fallback (var(--kit-mark-gap, var(--kit-sp-1))). The kit sets no component token; an app sets it, on :root or on the component.
  3. A rule of the app's own that selects a kit class, such as .kit-mark-version.
@layer app {
    :root { --kit-ink: #143f2a; --kit-on-ink: #ffffff; --kit-mark-gap: var(--kit-sp-2); }
    @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --kit-ink: #7fc8a2; --kit-on-ink: #000000; } }
    :root[data-theme="dark"] { --kit-ink: #7fc8a2; --kit-on-ink: #000000; }
    .kit-mark-version { color: var(--kit-fg-muted); }
}

A kit component is a name kit.manifest.json declares in its components, with its classes. Its parts keep single hyphens (.kit-mark-name): a class belongs to the longest declared component it starts with, so .kit-mark-name is kit-mark's, and a component's tokens are named --<component>-*, so --kit-mark-gap is kit-mark's. A new component is declared by adding its name to the manifest's components, a name that is a kit class some kit rule selects (kit-mark for .kit-mark); the manifest's regeneration test then fills in its classes.

An app's reset goes in the reset layer, below the kit's, so the kit's rules still apply over it. An unlayered rule beats every layer, so a legacy unlayered stylesheet on the same page (Bootstrap) overrides the kit. Import it into a layer the kit names instead, after KitHead: @import url("bootstrap.css") layer(reset);. A layer name kit.css does not declare lands above app, so a legacy stylesheet in a layer of its own would still beat the app's overrides.

kit.manifest.json, served at _content/Solhigson.Admin/kit.manifest.json, names every global token, component token, component and class the kit offers. A name leaving the manifest is a breaking change: an app's override of it stops applying, with no error.

Motion

Every motion the kit makes reads a duration token, --kit-d-1 (a hover), --kit-d-2 (an opening) or --kit-d-3 (a larger move). Every kit motion that takes time names its curve, a curve token, --kit-ease, --kit-ease-leave and --kit-ease-theme (something arriving or moving, something leaving, a theme's colours changing), or linear, a steady turn such as the busy ring's. Under prefers-reduced-motion: reduce every --kit-d-* token is 0ms and scroll-behavior is auto, so a viewer who asks for less motion sees none. A dwell token, named --kit-<component>-dwell, is a wait, not a motion: it keeps its time, so a confirmation still leaves after it.

A motion an app adds in @layer app reads a --kit-d-* token, so reduced motion stops it too; a component duration token of its own falls back to one (var(--app-panel-d, var(--kit-d-2))). An app that sets a duration token of its own repeats it as 0ms under prefers-reduced-motion too, since its value wins over the fallback. An app that overrides a --kit-d-* token repeats it as 0ms under prefers-reduced-motion, as a colour override gives its own dark value: the app's layer wins over the kit's reduced-motion block.

@layer app {
    :root { --kit-d-2: 160ms; }

    @media (prefers-reduced-motion: reduce) {
        :root { --kit-d-2: 0ms; }
    }
}

Buttons

KitButton renders a <button>, type="button" unless Type says otherwise, so a button inside a form submits it only when asked to. Variant is Default, Primary (the screen's one solid black element), Danger (the danger fill, for an action that cannot be undone) or Ghost (no fill or edge until hovered, for a toolbar or a row).

<KitButton Variant="KitButtonVariant.Primary" Type="submit">Save</KitButton>
<KitButton Href="~/users" class="app-wide">Users</KitButton>
<KitButton Href="~/users" Disabled>Users</KitButton>

With Href, it is a link, <a class="kit-btn">, to the address KitHref.LocalOrHttps makes of it (see Links). A refused Href, or Disabled on a link, renders <span aria-disabled="true">, which goes nowhere. Every other attribute passes through, and a class joins the kit's; a url attribute (formaction, ping, src and the like) is refused with an exception, since it would reach the page past KitHref.

Every variant is one control height tall: --kit-btn-height, falling back to --kit-control-h.

kit.forms.js marks the kit button that submits a form aria-busy="true" until the answer is on the page: Blazor's enhancedload for an enhanced form, pageshow for a full load. A busy button keeps its width: its label turns transparent in place and a ring turns at its centre. A submit some script cancels marks nothing, unless the form is enhanced (data-enhance): Blazor cancels that submit to post the form itself. A dialog form, or one aimed at another window, marks nothing either.

Status pills and alerts

KitStatusPill says a status in a word: Tone (Neutral, Success, Warn, Danger or Info) sets its colour, and Text, which it requires, says it, since a status is never colour alone.

KitAlert is a message about the page in the same tones, with an optional Title and its body as child content, its lines no wider than --kit-measure. A Neutral, Success or Info alert has role="status", which a screen reader reads when it is next idle; a Warn or Danger alert has role="alert", which it reads at once.

<KitStatusPill Tone="KitTone.Success" Text="Active" />
<KitAlert Tone="KitTone.Danger" Title="Not saved"><p>The email is taken.</p></KitAlert>

Form fields

KitField renders one labelled control with its hint and its error. Kind is Text, Email, Password, Number, Date, Search, Textarea, Select, Checkbox or Toggle; Name and Label are required.

<KitField Name="Email" Label="Email" Kind="KitFieldKind.Email" Value="@model.Email" Required
          Hint="We send the sign-in link here." Error="@errors.GetValueOrDefault("Email")" />
<KitField Name="Role" Label="Role" Kind="KitFieldKind.Select" Value="@model.Role" Placeholder="Choose a role"
          Options="@([("operator", "Operator"), ("approver", "Approver")])" />
<KitField Name="Notify" Label="Email me on changes" Kind="KitFieldKind.Toggle" Value="@model.Notify.ToString()" />
  • The <label> names the control by for and id; the hint and the error describe it by aria-describedby.
  • An Error marks the control aria-invalid="true" and shows its text after a glyph whose text alternative is the word "Error", so it is not colour alone. Static rendering posts a plain form, so the error text comes from the server; the field shows what it is given.
  • Required puts required on the control and a visible mark in the label, read as "(required)".
  • The id is kit-field- and the Name, every character that is not an ASCII letter or digit written as _ and its four hex digits (Items[0].Name is kit-field-Items_005B0_005D_002EName). It is the same on every render and different for every other name. Two fields of one Name on one page, in two forms, each need their own Id.
  • A Password never writes Value into the page, so a stored secret shows only as set or not set; it carries autocomplete="new-password" unless AutoComplete says otherwise, since browsers ignore off on a password and would fill the administrator's own saved password.
  • A Select takes its Options as value and text pairs, in order; the option whose value equals Value, compared ordinally, is selected. Placeholder adds a first, empty option, chosen when Value is empty.
  • Min, Max and Step are a Number's or a Date's; ReadOnly is an input's or a textarea's, since a browser lets a select, a checkbox and a toggle change though they are read-only (use Disabled). A parameter the kind cannot honour is refused with an exception, as are Options on any kind but a Select.
  • Every other attribute lands on the control. The field owns id, name, required, disabled and aria-invalid on every control; type, value, placeholder, min, max, step, readonly and autocomplete on an input; placeholder, readonly and autocomplete on a textarea; autocomplete on a select; type, value and checked on a box or a toggle; and role on a toggle. It writes them after the caller's, so a passed one is replaced; set them through the parameters. A passed class and a passed aria-describedby join the field's own. A url attribute is refused, as KitButton refuses it.
  • An input and a select are one field height tall: --kit-field-height, falling back to --kit-control-h.

A Checkbox or a Toggle posts value="true" when ticked and nothing at all when not: there is no hidden field. It is ticked when Value is true in any case, so Value="@model.Notify.ToString()" works. A handler reads an absent box as false by binding it to a bool, which the absent field leaves false: [SupplyParameterFromForm] public bool Notify { get; set; } in a component, or a bool property of an MVC model. A Toggle is the same checkbox with role="switch", drawn as a track and a thumb, so it never looks like a box to tick.

A disabled field, like an unticked box, posts nothing, and a viewer can post any field the page never showed them. So a handler writes only the fields the signed-in viewer may change, decided by their permission on the server, never by which fields arrived or which the page disabled, and leaves every other value as stored.

Setting fields

KitSettingField shows one declared setting as a row of a settings list: its label and purpose, one control of its kind (KitSetting.From makes its Setting from the framework's DeclaredSettingLine), the hint with its bounds and default, where its value comes from, and a pill and a sentence for each flag. A Secret, a row stored sensitive and a value shown as the mask are a password field that starts empty; nothing of the value is written into the page. With ReadOnly, or on a line that cannot be edited, the row shows its value as text, "Hidden" for one that may not be shown.

KitSettingField renders no form of its own: the screen places each setting in a form of its own, with its Save button. Its controls post the bare names Value, Amount and Unit (a duration as an amount posts Amount and Unit; every other kind posts Value), so the screen binds them with [SupplyParameterFromForm(Name = "")] and turns them into the setting's text with KitSettingValue.Compose:

<form method="post" @formname="setting" @onsubmit="Save">
    <AntiforgeryToken />
    <KitSettingField Setting="@setting" Fields="@Posted" Error="@error" />
</form>

@code {
    [SupplyParameterFromForm(FormName = "setting", Name = "")]
    private KitSettingFields? Posted { get; set; }

    private void Save() => composed = KitSettingValue.Compose(setting, Posted);
}

An unticked toggle posts nothing, so Value binds null, which KitSettingValue.Compose reads as false; when the toggle is the form's only field the whole KitSettingFields binds null, which Compose reads the same way. A line shown as the mask is the exception: controls left empty compose to the mask, which the framework's save reads as no change.

ChildContent, when given, is placed last in the row, in the control's column under the hint, the error and the lines, in a box of its own (kit-setting-actions) that stacks what it holds a section step apart. The settings screen puts its buttons and what a post came to there, so they sit inside the row they act on; with none given, no box is drawn.

<KitSettingField Setting="@setting" Fields="@Posted" Error="@error">
    <div class="kit-settings-actions">
        <KitButton Type="submit" name="op" value="save">Save</KitButton>
    </div>
</KitSettingField>

Dialogs and confirms

KitDialog renders the browser's own <dialog>, which gives the backdrop, the focus trap and Escape. Variant is Modal, a box in the middle that rises as it opens, or Drawer, a panel the screen's full height at its inline-end edge that slides in; both are still under reduced motion. It is labelled by its Title, and its close button closes it and posts nothing (formmethod="dialog" and formnovalidate).

Any element with data-kit-open="<id>" opens the dialog of that id, which kit.dialog.js looks up at the click, so a dialog an enhanced navigation removed is simply not opened. A click outside the dialog's box, on the backdrop, closes it. An opener inside a popover hides the popover first, and the popover's trigger takes the focus back when the dialog closes.

<KitButton data-kit-open="remove" data-kit-fill-user-id="@user.Id" data-kit-fill-name="@user.Name">Remove</KitButton>

<KitConfirm Id="remove" Title="Remove this user?" FormAction="~/users/remove" FormName="remove-user"
            Fields="@(["user-id"])" ConfirmText="Remove">
    <p><span data-kit-slot="name"></span> is signed out and cannot sign in again.</p>
</KitConfirm>

Before it opens, the script clears every marked target it can fill, then copies each data-kit-fill-<name> of the opener, as text, into the target of that name, matched ignoring case. A target is an element with data-kit-slot="<name>", or a control marked data-kit-fillable that is a textarea or an input of one of six types: hidden, text, search, email, tel or url. A marked control of any other type (a checkbox, a radio, a file input, a number) or a select is never cleared or filled. Only marked fields are filled, so a form the server filled in a dialog keeps its values; KitConfirm marks its hidden fields. One dialog can serve a whole list this way, and it never shows or posts the last row's values. A name is lower-case letters and digits joined by hyphens. A name starting _ is never filled, so a row cannot overwrite the form's _handler or its antiforgery token. An opener marked aria-disabled="true" opens nothing.

With FormAction and FormName, a dialog's title, body and footer sit in one <form method="post"> with @formname and the antiforgery token, Blazor writing the form's _handler field itself; a footer button with Type="submit" posts the body's fields to the action, and a handler with that FormName receives it. The action goes through KitHref.Local: a path on this site or a ~/ path, joined to the request's path base. A refused action renders no posted form; the dialog then only closes. KitConfirm is such a dialog with a hidden field for each of its Fields, a cancel button that sends nothing, and a confirm button, Danger unless ConfirmVariant says otherwise; a confirm whose action KitHref.Local refuses throws, since a confirm must post.

A confirm posts to the page that renders it, to an endpoint that is not a Blazor page (a minimal API or an MVC action, which reads the token itself), or to a Blazor page that renders a form of the same name. A Blazor page that only binds the name, with [SupplyParameterFromForm(FormName = …)] and no such form, answers the post with 400.

A component that handles its own confirm passes OnConfirm. The confirm's form is then a named form with that handler on it (KitDialog's OnSubmit), so the post runs the handler in the request that renders the page again, after the component has bound the fields with [SupplyParameterFromForm(FormName = …)]. The confirm must be rendered in that request too, or Blazor answers the post with 400. Without OnConfirm the form carries no handler, as before.

Row menus

KitMenu renders a row menu on the browser's own popover: a trigger, a ghost KitButton with popovertarget and aria-haspopup="menu", showing three dots with its Label as aria-label (or its label as text with ShowLabel), and a popover panel with role="menu". The browser opens the panel and closes it on a click outside it or on Escape; kit.menu.js places it under its trigger and inside the viewport, focuses its first item, and moves among the items with the arrow keys, Home and End. Each row's menu needs its own Id, unique on the page.

@foreach (var user in users)
{
    <KitMenu Id="@($"user-{user.Id}-menu")" Label="@($"Actions for {user.Name}")">
        <KitMenuItem Href="@($"~/users/{user.Id}")">Open</KitMenuItem>
        <KitMenuItem OpenDialog="remove" data-kit-fill-user-id="@user.Id" data-kit-fill-name="@user.Name" Danger>Remove</KitMenuItem>
        <KitMenuItem Action="~/users" FormName="disable-user" name="user-id" value="@user.Id">Disable</KitMenuItem>
    </KitMenu>
}

<KitMenuForm FormName="disable-user" Action="~/users" OnSubmit="Disable" />

Each KitMenuItem, role="menuitem", is one of four kinds:

  • a link, Href through KitHref.LocalOrHttps;
  • a dialog opener, OpenDialog naming a KitDialog or KitConfirm, with its data-kit-fill-<name> values written on the item as on any opener; the dialog script hides the menu first and gives its trigger the focus back on close;
  • a post button, which submits the KitMenuForm of its FormName (form=) to its own Action (formaction=, through KitHref.Local), with the name and value written on the item: the pressed row's value alone is posted;
  • a theme choice, ThemeChoice light, dark or system, a role="menuitemradio" that kit.theme.js switches as it switches a KitThemeSwitch choice, aria-checked on the theme the server read.

The page places one KitMenuForm for each FormName, outside any form, since a form inside a form is dropped and Blazor refuses a post to a page holding two forms of one name. It is hidden, and carries the action, the @formname and the antiforgery token, Blazor writing the _handler field itself; its OnSubmit runs when the form is posted to the page and may redirect. A post item whose FormName has no KitMenuForm on the page would submit nothing, so kit.menu.js shows it disabled, at start and after every enhanced navigation, and warns in the console which form id is missing. The KitMenuForm must sit outside any form: inside one it is dropped, its fields join the enclosing form, and a GET form would put the antiforgery token in the url. A post item may post to the page that renders its KitMenuForm, to an endpoint that is not a Blazor page (a minimal API or an MVC action, which reads the token itself), or to a Blazor page that renders a KitMenuForm of that name; a Blazor page that only binds the name, with [SupplyParameterFromForm(FormName = …)] and no such form, answers the post with 400.

A target KitHref refuses renders the item as disabled text (aria-disabled="true"), which takes no focus. Danger marks a destructive item. Every other attribute lands on the item's element; a url attribute and a name starting _ are refused.

The admin shell

KitShell is the layout an app's layout wraps its pages in. It renders, in order, a skip link to the main region, a side rail (<nav aria-label="Main">) with the Brand and the Menu, a top bar holding the user's menu, and <main id="kit-main"> holding the page, with any Messages above it as KitAlerts. It adds no script.

@inherits LayoutComponentBase

<KitShell Brand="Elfrique Admin" Menu="@menu" UserName="@user.Name" Messages="@messages"
          SignOutAction="~/account/sign-out" SignOutFormName="sign-out" OnSignOut="SignOut">
    @Body
</KitShell>

@code {
    private IReadOnlyList<KitNavItem> menu =
    [
        new("dashboard", "Dashboard", "~/", Current: true),
        new("people", "People", Children: [new("users", "Users", "~/users"), new("roles", "Roles", "~/roles")]),
    ];
}

A KitNavItem has a Key, its text, an href, children and Current. An item with children is a group, a native <details> with a chevron, open when it holds the current item; a group with an href too is refused, naming its Key. The current item carries aria-current="page" and shows it by weight and the surface's soft fill, never the ink. An href goes through KitHref.Local, since a menu is often stored rows an administrator can edit: an item with no href (one an on-click function drove, say) is text and logs nothing, and one whose href KitHref.Local refuses is text and writes one Warning naming the item's Key, never its href, under the Solhigson.Admin.Components.KitShell category on every render. Every Key must be an id token: set, with no white space, control or format character, so a Key can forge no log line.

The user's menu, a KitMenu labelled with UserName, holds the three theme choices and sign-out. Sign-out is a post, never a link: a post item submitting the KitMenuForm the shell places after itself, outside any form, built from SignOutAction (through KitHref.Local, which must accept it) and SignOutFormName. Sign-out posts either to a page rendering the shell, where Blazor checks the token and OnSignOut runs and may redirect, or to an endpoint that is not a Blazor page (an MVC action or a minimal API), which checks the antiforgery token and signs out itself. The theme choices are menuitemradio items; the checked one shows a tick.

The rail is soft grey (--kit-ink-soft). At 720px and under it is one row above the page that scrolls inside itself, so the page never scrolls sideways. An item under the pointer takes the text colour; the current one also takes the surface's fill and is heavier. The skip link is hidden as .kit-sr text is until a keyboard focuses it. Its href is the page's own url and #kit-main, so it stays on the page under a <base href>, where a bare #kit-main would resolve against the base. The url is the one the browser asked for, the original one on a re-executed status code page, through KitHref.Local, and a url it refuses leaves the bare #kit-main; it carries data-enhance-nav="false", so Blazor does not fetch the page again for it.

The menu from permissions

IKitMenuSource builds the shell's menu from the permissions the signed-in user's roles hold, read through the framework's PermissionManager (its cached menu read, and its cached read of every permission a role holds). Register it beside the identity manager, with the same type arguments:

builder.Services.AddSolhigsonIdentityManager<AppUser, AppDbContext>();
builder.Services.AddSolhigsonAdmin<AppUser, AppDbContext>();

AddSolhigsonAdmin<TUser, TKey, TContext>() is the overload for a key type other than string. Either registers the menu source and the audit seam, both scoped (see Recording changes), and IHttpContextAccessor, which the audit seam reads the signed-in user through, and nothing else. The layout passes the menu to KitShell, and says so on the page when it could not be read, since an empty rail would otherwise read as a revoked grant:

@inherits LayoutComponentBase
@inject IKitMenuSource MenuSource

<KitShell Brand="Elfrique Admin" Menu="@_menu.Items" Messages="@_messages" UserName="@HttpContext!.User.Identity?.Name"
          SignOutAction="~/account/sign-out" SignOutFormName="sign-out">
    @Body
</KitShell>

@code {
    private KitMenuResult _menu = new([], false);
    private IReadOnlyList<KitMessage>? _messages;

    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override async Task OnInitializedAsync()
    {
        _menu = await MenuSource.ForAsync(HttpContext!.User, HttpContext.Request.Path, HttpContext.RequestAborted);
        _messages = _menu.Failed ? [new(KitTone.Danger, "The menu could not be loaded. Reload the page to try again.")] : null;
    }
}

The menu shows; it does not enforce: each page's [Permission] is the gate. The roles are the principal's role claims, as [Permission] reads them, so the menu and the gate agree for the life of a cookie; a user who is not signed in, or who holds no role, is shown nothing. A permission the roles hold is an item, keyed by its name, its text the description or else the name, its href the stored url. A parent they do not hold is shown only as the label of a held child, and only when it is enabled; a disabled parent takes its children with it. A held parent with a url of its own and held children is a group whose first item is its own link. The order is the stored menu index, then the name. The current item is the one whose url, ~/ read as /, is the request's path without its path base, ignoring a trailing slash and case.

The source writes to none of the manager's cached answers: each item is a new object, so one user's menu never reaches another's. The answers are cached, so a grant shows when the cache next refreshes, as it does at the gate. A fault answers an empty menu with Failed set and writes one Error under Solhigson.Admin.Navigation.KitMenuSource, with the exception, the permission manager and the role names, any control or format character in a name written as its \uXXXX escape; the request's cancellation propagates and logs nothing. A permission whose name is no id token, which KitShell cannot key an item by, is left out with its children, and named by its id in one Warning.

Page header, lead, empty state and pager

A list screen opens, reads and pages the same way: KitPageHeader holds the title as the page's one <h1> (in the serif face), an optional Line under it, a subtitle such as a count or a scope, no wider than the measure, and an optional Actions slot at the title's end, which moves under the title when the header is 400px wide or less. A screen's purpose sentence is not the header's line: it is KitLead, a page's or a section's one lead sentence, at a section heading's size; it is a paragraph, never a heading.

<KitPageHeader Title="Users" Line="@($"{page.Total} users, {page.Invited} invited")">
    <Actions>
        <KitButton Variant="KitButtonVariant.Primary" Href="~/users/new">New user</KitButton>
    </Actions>
</KitPageHeader>
<KitLead>Who can sign in to the admin, and what each may do.</KitLead>

@if (page.Rows.Count == 0)
{
    <KitEmptyState Title="No users match" Line="No user matches these filters." ClearHref="~/users" />
}

<KitPager NextHref="@(page.NextHref)" FirstHref="@(page.FirstHref)" />

The hrefs are written @(page.NextHref): Razor reads a bare @page as the page directive.

KitEmptyState says what is empty and why, its title an <h2>, with an optional Action (such as a link to create the first row). With ClearHref it is the "no match for these filters" form and offers a "Clear filters" link; without it, the "nothing here yet" form, which offers the next step:

<KitEmptyState Title="No roles yet" Line="A role groups the permissions a user may hold.">
    <Action>
        <KitButton Variant="KitButtonVariant.Primary" Href="~/roles/new">Create the first role</KitButton>
    </Action>
</KitEmptyState>

A list whose viewer cannot add rows shows no action, and names in its Line who can: "An administrator adds roles." The empty state's action is Primary only when the header holds none: when the header already offers it, the empty state's button is Default, or the empty state leaves the action to the header, so a screen has one Primary action.

KitPager pages a keyset list with links: forward to NextHref, which carries the next page's cursor, and back to FirstHref; a keyset cursor has no previous page. With both it shows "First page" and "Next page"; with NextHref alone, the first page of several, "Next page"; with FirstHref alone, the last page, "First page" and "End of list"; with neither, nothing. Every href goes through KitHref.Local and a refused one renders no link; a refused NextHref shows no link and no "End of list", since the list may go on. A cursor in a link shows in the address bar, so it holds ids and instants alone, as the framework's do.

Data table and filter bar

KitTable<TRow> lists Rows under KitColumn<TRow>s, each a sentence-case Title and a cell, a template over the row that holds components and text, which Razor encodes: a cell is never an HTML string. Align="KitAlign.End" ends a column of numbers and sets them in tabular figures; Priority="KitPriority.Low" hides a column when the table is 720px wide or less, so a phone keeps the columns that matter in view, and the table scrolls sideways inside its own wrapper rather than widening the page. The columns are collected before the table is drawn, so one static render shows every header and cell; a column takes its row type from its table. Caption names the table for a screen reader, and shows with ShowCaption; Empty shows in the table's place when there is no row.

<KitTable Rows="@users" Caption="Users">
    <Empty>
        <KitEmptyState Title="No users match" Line="No user matches these filters." ClearHref="~/users" />
    </Empty>
    <ChildContent>
        <KitColumn Title="Name">@context.Name</KitColumn>
        <KitColumn Title="Status"><KitStatusPill Tone="@context.Tone" Text="@context.Status" /></KitColumn>
        <KitColumn Title="Sign-ins" Align="KitAlign.End" Priority="KitPriority.Low">@context.SignIns</KitColumn>
        <KitColumn Title="Actions" HideTitle Align="KitAlign.End">
            <KitMenu Id="@($"user-{context.Id}-menu")" Label="@($"Actions for {context.Name}")">
                <KitMenuItem Href="@($"~/users/{context.Id}")">Open</KitMenuItem>
            </KitMenu>
        </KitColumn>
    </ChildContent>
</KitTable>

HideTitle keeps a column's header for a screen reader alone, for a column whose cells say what they are, such as a row's menu. There is no sort or row-open script: a sortable column is a link the app writes in its cells or above the table.

KitFilterBar is a plain form around the app's KitFields, with an "Apply" button, a Default one since the screen's Primary action stays the header's, and, with ClearHref, a "Clear" link; it wraps onto as many rows as the width needs, and opts in to enhanced form handling (data-enhance), so the list is swapped in place. Method is KitFormMethod.Get unless set, so a filtered list has an address a user can keep and share. A filter on a personal value, such as an email or a name, uses Method="KitFormMethod.Post", so the value stays out of the address, the access log and the browser's history; a Post filter takes a FormName, its @formname, and carries the antiforgery token, Blazor writing the _handler field itself, and the page binds the fields with [SupplyParameterFromForm(FormName = …)]. Action, the page's own address when unset, and the clear link go through KitHref.Local: an Action it refuses throws, and a refused clear link is not shown. A list filtered by a Post keeps its filter on the server, in the session or behind an opaque server-side cursor, so the pager's links carry no personal value; or it is one page, with no pager.

<KitFilterBar ClearHref="~/users">
    <KitField Name="role" Label="Role" Kind="KitFieldKind.Select" Options="@roles" Value="@Role" />
</KitFilterBar>

<KitFilterBar Method="KitFormMethod.Post" FormName="find-user" ClearHref="~/users">
    <KitField Name="email" Label="Email" Kind="KitFieldKind.Email" Value="@Email" />
</KitFilterBar>

The settings screen

KitSettingsEditor is the settings screen: every setting the app's catalogue declares, one section a group in the order the catalogue registered them, each setting a KitSettingField row in a box whose id is kit-setting- and its key, written as a field's id writes a name. Its header, titled "Settings", counts the settings and, when a setting carries a flag or the table holds a row no setting declares, links to the "needs attention" filter, saying how many. Above the groups it shows a warning that a secret's save is refused while the legacy encryptor is in force and a setting is a Secret or stored sensitive; the attention view also says how many stored rows match no declared setting, and that a row is cleared when the app declares it in its catalogue, or it is removed from the settings table. Under the groups, the section "Rows with no declaration" lists those rows (see Removing a row no setting declares). A GET filter bar finds settings by words in their key, name or purpose, never in a value, and by "needs attention". A component cannot be given a route, so the app writes the page:

@page "/admin/settings"
@using Microsoft.AspNetCore.Authorization
@using Solhigson.Framework.Web.Attributes
@using Solhigson.Framework.Web.Authorization
@attribute [Permission("settings.view")]
@inject IAuthorizationService Authorization

@if (canEdit is bool edit)
{
    <KitSettingsEditor CanEdit="@edit" />
}

@code {
    private bool? canEdit;

    [CascadingParameter]
    private HttpContext? HttpContext { get; set; }

    protected override async Task OnInitializedAsync()
    {
        var decision = await Authorization.AuthorizeAsync(HttpContext!.User, PermissionPolicy.For("settings.edit"));
        canEdit = decision.Succeeded;
    }
}

The page's [Permission] lets a viewer see the screen; CanEdit, false unless set, is a second permission's, decided on the server. Without it a Personal value is shown as "Hidden", and the listing is read outside a write session; with it the value is in its field. A Secret's value is never written into the page, with or without it. The sample renders the editor once canEdit is decided. An editor whose CanEdit changes lets a read in flight end and reads the listing again, and a render, a streamed one included, shows only a listing read with the CanEdit in force, so none shows a Personal value that CanEdit forbids; a read that failed is not made again, so one fault is one Error and one alert.

The app must have called RegisterSolhigsonDependencies with a database (or RegisterSolhigsonDependenciesWithProvider), which registers the SolhigsonConfigurationService and the ConfigurationWrapper the editor injects. It registers its settings catalogue at start (SolhigsonConfigurationService.UseSettingsCatalog); until it does, the screen shows the empty state "No settings are declared", and a registered catalogue that declares nothing shows "The catalogue declares no setting". AddRootEncryption at start lifts the warning on a secret's save.

The page refuses framing, so no other site can lay the screen under a decoy. The app must send X-Frame-Options: DENY and Content-Security-Policy: frame-ancestors 'none' on this page; the framework and the template send neither, and the editor sets no header.

A listing that cannot be read shows a Danger alert, "The settings could not be loaded", and writes one Error under Solhigson.Admin.Components.KitSettingsEditor, naming the component, with the exception; the page holds none of its text. The request's own cancellation propagates and logs nothing.

Saving and resetting a setting

With CanEdit true, every line is a form of its own. The form posts to the page's path and the row's id, without the filter's query, so the posted line is on the page whatever filter it matched. Each form sits in a FormMappingScope named from its key, and Blazor writes its _handler, such as [SignIn_003AMaxAttempts]setting; the form also holds the antiforgery token, the key and the field. A line shows:

  • "Save" when it can be edited, but a toggle. A toggle shows no "Save": it saves when it changes. Its "Save" is inside <noscript>, for a browser that runs no script. A toggle that can also be reset has a visually hidden "Save" as its form's first submit button, so Enter in the form saves it and never resets it. The button is clipped to nothing (kit-sr) rather than not rendered, since a browser may skip a button with no box when Enter submits; it is out of the tab order (tabindex="-1") and of the accessibility tree (aria-hidden="true").
  • "Reset to default" when the listing calls it resettable. A Secret shows it only while a row of it that no read sees is stored.
  • The reset alone when it cannot be edited but can be reset, such as a Startup setting's row.
  • No button when it can be neither saved nor reset. Its form is still there, so a form posted after its line lost its last button is answered at the line.

Every button is named op, its value save or reset; the alerts and buttons sit under the field, in its column.

With CanEdit false no form is rendered, so a post gets the framework's 400 and nothing is written. The handler also checks CanEdit before any call, so a post that reaches it in another way writes nothing.

A line whose value may be shown also posts the row state it was loaded with. The save passes that state on as its SettingLoad, so a save of a row changed since the page loaded is refused. A Secret, or a row stored sensitive, posts no row state. A post whose key is not its form's, whose row state the page did not write, or whose button no form has, saves nothing and says "This form is out of date: nothing was saved."

The outcome is said at the line:

Outcome Shown as
Saved A Success alert, "Max attempts saved."
Reset A Success alert that names the value now in force.
No change, or no row to reset A Neutral note that nothing changed.
A Secret posted blank A Neutral note that the stored secret was kept.
Refused The sentence beside the field, which keeps what was typed but never a secret's. A line with no field shows it in a Warn alert. The sentence names the setting by its label and says what to enter, such as "Enter a whole number from 1 to 10.", never the key in brackets or the declaration's terms.
Changed since the page loaded A Warn alert that nothing was saved and names the value now stored, which the field then shows.
Failed A Danger alert that nothing was saved, with no exception text.
Cache not told A Warn alert that other instances may show the old value until their settings cache recovers.

A setting no longer declared when its save runs has no line, so its outcome is said above the groups.

Removing a row no setting declares

Under the groups, the section "Rows with no declaration" lists each stored row the catalogue does not declare in a KitTable: its name, and its flags as the setting field's short pills, such as "Looks secret". No value is shown, since nothing says whether such a row holds a secret. The filters leave the section as it is, so the "needs attention" view shows it too. The section is not rendered when no catalogue is registered, when the catalogue declares no setting, or when no such row is stored: with no catalogue every row would be listed.

With CanEdit true, each row has a "Remove" button. It opens one KitConfirm, "Remove this row?", filled with the row's name: "The row … matches no declared setting. Older code may still read it by name, and this screen cannot put it back." The confirm's "Remove row" posts the name to the page's path and the section's id, #kit-settings-stray. The editor handles the post itself (OnConfirm), with the handler stray-remove. It checks CanEdit before any call, then calls the framework's RemoveUndeclaredRowAsync, which judges the name again: a name a setting declares, or a row the database matches to one, is refused. The confirm is rendered whenever a removal could be made, so a confirm posted after its row went is answered; with no stray row left, the section shows its heading and the outcome alone.

The outcome is said under the section's heading, above its table:

Outcome Shown as
Removed A Success alert, "The row Retired:Banner was removed."
No such row A Neutral note, "No stored row is named Retired:Banner; nothing was removed."
Belongs to a setting A Warn alert naming the setting by its label, "Nothing was removed: SignIn:MaxAttempts belongs to the setting Max attempts. Reset that setting above instead."
Refused otherwise A Warn alert with the framework's sentence, opening "The row Retired:Banner was not removed."
Failed A Danger alert that nothing was removed, with no exception text.
Cache not told A Warn alert, as for a save.

With CanEdit false neither the buttons nor the confirm are rendered, so a post gets the framework's 400 and nothing is removed; the handler's own check covers a post that reaches it another way. Neither is rendered either when KitHref.Local refuses the page's path as the confirm's action, such as a path holding an escaped backslash that reaches the page by an optional route part.

Recording who changed a setting

Each save, reset or removal done is recorded through the audit seam, IKitAudit (see Recording changes), after it is done. The audit row holds:

  • the category SecurityEvent;
  • the action settings.saved, settings.reset or settings.stray-removed (KitAuditActions);
  • the entity type AppSetting, with the setting's key, or the removed row's name, as both the entity id and the subject's display name;
  • the actor;
  • a payload of the key, PreviousShown and NewShown, the values before and after as the framework's result shows them. A Secret's value, a row stored sensitive and a Personal value are the mask. A removal's NewShown is null, and its PreviousShown is the value removed: the mask for a row stored sensitive or under a secret-looking name, else the value, which is what a developer puts back.

A refusal, no change, a change made elsewhere and a failed save or removal change nothing, and record nothing.

When the record cannot be written, the change is not undone. The two are written by different contexts, so the screen shows the Success alert and a Warn alert: "No audit record was written for this change. Record it by hand if the audit trail must hold it; the app's log holds the error." A reset's says "this reset", a removal's "this removal".

When no change can be recorded, the screen shows a Warn alert above the groups with CanEdit true, titled "Changes here leave no audit record". The read-only screen, where nothing changes, does not show it. No change can be recorded when:

  • IKitAudit is not registered;
  • no audit service resolves;
  • the app's context does not map AuditTrail and no IAuditSink is registered.

The record is written with no cancellation, so a save is recorded even when the operator has left the page.

The screen writes one log line, under Solhigson.Admin.Components.KitSettingsEditor. The audit seam writes its own lines under Solhigson.Admin.Auditing.KitAudit (see Recording changes). The save, the reset and the removal write theirs under Solhigson.Framework.Infrastructure.ConfigurationWrapper, with the setting's key and never its value when the value may not be shown. The settings cache's invalidation writes under Solhigson.Framework.EfCore.Caching.EfCoreCacheManager, and its Redis change tracker under Solhigson.Framework.EfCore.Caching.MemoryCacheProvider:

Line Level Text What to do
KitSettingsUnlisted Error {Component} could not read the settings listing, so the page shows that the settings could not be loaded. Read the exception; fix the database or the catalogue it names.
Saved Information The setting [{setting}] was saved: {previous} to {saved}; cache confirmed {cacheConfirmed}. Nothing. A False means other instances may show the old value until their cache recovers.
Reset Information The setting [{setting}] was reset: {removed} row(s) removed, {previous} to {inForce}; cache confirmed {cacheConfirmed}. As for Saved.
Removed Information The undeclared row [{setting}] was removed; cache confirmed {cacheConfirmed}. As for Saved.
Not declared Warning A {save|reset} named the setting [{setting}], which is not declared; nothing was {saved|reset}. Declare the setting in the catalogue, or stop posting it.
Not done Warning The setting [{setting}] was not {saved|reset|removed}: {reason} Act on the reason: a setting read at start is changed in configuration; a row nothing would answer without keeps its value; a declared setting's row is reset, not removed.
Refused Warning The setting [{setting}] was not {saved|reset|removed}: {rule}. Act on the rule: a value in bounds, a page loaded again, or AddRootEncryption for a secret.
Saved plain Warning The setting [{setting}] is saved plain although its name {reason} (term '{term}'): its value is a flag or a number. Check the name does not hold a secret.
No catalogue Warning No settings catalog is registered (SolhigsonConfigurationService.UseSettingsCatalog), so a settings table write is held to no declaration, only to the encryptor and secret-name rules. Logged once per process. Register the catalogue at start.
Failed Error {Saving|Resetting|Removing} the setting [{setting}] failed. Read the exception; the screen said nothing was done, so the operator tries again.
Cache timed out Warning [{CacheType}]: Invalidation of {Types} did not complete within {Timeout} The value is stored; other instances may serve the old value until their cache entry expires. Check the cache store (Redis) and its latency.
Cache failed Warning [{CacheType}]: Invalidation of {Types} failed Read the exception; as for a timeout, other instances may serve the old value until their cache entry expires.
Cache not invalidated Error [{CacheType}]: Unable to invalidate cache A fault other than Redis's in the save's own invalidation (the EF Core interceptor's). Read the exception; other instances may serve the old value until their cache entry expires.
Change tracker unavailable Warning Change tracker unavailable: {Kind} ({Reason}) on {Channel}; entries cached before the outage are served until they expire or the tracker recovers, nothing new is cached, and the poll retries Redis every {Interval}; a writer should use InvalidateAndWaitAsync to confirm a change was published Logged once per outage, by the first call that finds Redis down, the save's invalidation included; a Redis failure the save meets writes neither "Cache failed" nor "Cache not invalidated". Restore Redis; until then the screen says the cache was not told.
Change tracker available again Warning Change tracker available again: Redis answered; {Lost} invalidations were lost on this pod during the outage ({Resend}) Closes the outage, once. Nothing, unless the lost invalidations were not sent again.

Recording changes

IKitAudit (Solhigson.Admin.Auditing) is the one seam through which every admin screen records a change it made. AddSolhigsonAdmin registers it, scoped, as KitAudit<TContext> over the app's identity context TContext. The app must map AuditTrail in that context's OnModelCreating and migrate, or register an IAuditSink that writes the rows elsewhere. The framework's RegisterSolhigsonDependencies registers the audit service, IAuditTrailService<TContext>. That registration is made through Autofac, which the service collection does not see. So the seam resolves the audit service, the actor provider and the context from the request's services at first use, not at registration.

TContext must be registered scoped, as AddDbContext and the framework's Autofac module register a context. The seam looks for an unsaved row on the instance it resolves, which must be the one the framework's service wrote on.

  • Records is false when no audit service resolves, or when the context does not map AuditTrail and no IAuditSink is registered. The framework's service would then drop the row with a log line, so the seam does not say a row was written. A screen asks Records to say on the page that its changes are not recorded. An app that never called AddSolhigsonAdmin gets a seam whose Records is false.

  • RecordAsync(KitAuditEvent, CancellationToken) writes one row and answers whether it was written; handed to the app's sink counts as written. It throws only the caller's own cancellation. A write that throws is logged and answered false. The framework's service swallows a failed write, so the seam also answers false in two cases:

    • A row the service left unsaved on the context. The seam detaches it, so no later save in the request writes it.
    • A sink that threw. With a sink and the framework's own service, the seam writes through an instance of that service of its own, over the app's sink behind a watch, and reads what the handoff threw. The container's registrations are left as they are, so no other caller resolves the watch.

    With an audit service of the app's own in place of the framework's, the seam answers false for what that service throws, and cannot see what it swallows: a write it swallows is answered true.

  • KitAuditEvent carries the category, the action, the subject's entity type, id and display name, and the payload. The payload is stored as it is: the framework masks nothing on this path, so a screen passes a projection that holds only what the row may show.

  • The actor is the app's IAuditActorProvider's. The framework's default provider gives the unattributed actor. When it does and the request is signed in, the actor is built from the principal: its id is the NameIdentifier claim, or sub when it has none, its name is Identity.Name, and its source is web. A provider of the app's own that names an actor is used as it is.

The seam writes these lines under Solhigson.Admin.Auditing.KitAudit, with the entity id (a setting's key) and never the actor or a value:

Line Level Text What to do
KitAuditOff Warning Admin changes are not recorded in the audit trail: {Reason} Each admin screen that changes data says so above its content. Logged once per process. Act on the reason: register the audit service (RegisterSolhigsonDependencies), map AuditTrail in the context and migrate, or register an IAuditSink; call AddSolhigsonAdmin when the seam is not registered. A reason that the service could not be resolved carries the exception.
KitAuditFailed Error The audit row of {Action} on [{EntityId}] was not written; the change itself was made, and is not undone. Read the exception (the audit service's, or the sink's) and fix the audit store. The change has no audit row, so record it by hand if the audit trail must hold it.
KitAuditUnsaved Error The audit row of {Action} on [{EntityId}] was not written: the audit service left it unsaved, and its own log line holds the cause; the change itself was made, and is not undone. Read the framework's line under AuditTrailService, "Explicit audit event was swallowed under the never-block invariant", for the exception, and act as for KitAuditFailed.

KitGallery shows every kit component, in every variant and state, on fixed example data, so a look is judged in both themes (its theme choices switch the page) before a screen uses it. Each section is headed by the component's name and the component tokens the manifest names for it; KitShell is shown once, in an inert frame, so its landmarks and skip link never stand beside the page's own. The gallery has no shell of its own, so the app's layout wraps it as any page, and its title is the page's one <h1>. An app cannot be given a route by a component, so the app writes the page that hosts it:

@page "/kit-gallery"
@using Solhigson.Framework.Web.Attributes
@attribute [Permission("kit.gallery")]

<KitGallery />

Add it only in development, or behind a permission, as the sample's [Permission] puts it: it shows nothing secret, but it has no purpose in production. An app that wants it in development alone writes that condition in the page in place of the attribute: @inject IWebHostEnvironment Environment, then @if (Environment.IsDevelopment()) { <KitGallery /> }. Every example link and post on it targets the page itself.

KitHref is the one way a kit component takes a url. Blazor encodes an attribute's value but refuses nothing, so javascript:alert(1) or //elsewhere.example written into an href runs or leaves the site. KitHref.Local(value, pathBase) answers a path on this site or null: a path starting with one /, or one starting with ~/, which it joins to the request's path base. It refuses a value holding a control character or white space, and a path part that starts with //, holds a . or .. segment or a backslash, written or percent encoded. KitHref.LocalOrHttps also accepts an absolute https:// address with no user name in it. Each also takes the request itself, KitHref.Local(value, HttpContext) and KitHref.LocalOrHttps(value, HttpContext), and reads its path base.

A stored menu url starts with ~/, which a Razor component does not resolve. Hand it to KitButton.Href as stored, or resolve it for a link of the app's own with the request's path base, and leave the link out when the answer is null:

@code {
    [CascadingParameter] private HttpContext? HttpContext { get; set; }

    private string? Target(string stored) => KitHref.Local(stored, HttpContext);
}

Light and dark

A page follows the viewer's system theme until the viewer picks one. KitThemeSwitch (Solhigson.Admin.Components) renders the choice, Light, Dark or System, as three ghost buttons in one group, the current one aria-pressed="true". A click switches the page at once, with no round trip: kit.theme.js sets data-theme on the <html> element and keeps the choice a year in the cookie kit-theme (Path=/, SameSite=Lax, Secure on an https page), or, for System, removes data-theme and deletes the cookie.

The server renders the choice, so the first paint is already right. KitTheme.Current(HttpContext) (Solhigson.Admin.Theme) reads the cookie as exactly light or dark, and anything else as no choice; the cookie's text never reaches the page. A component cannot set attributes on the app's <html>, so the app splats KitTheme.HtmlAttributes on it, in its root component:

@using Solhigson.Admin.Theme

<html lang="en" @attributes="KitTheme.HtmlAttributes(HttpContext)">
    <head>
        <KitHead Nonce="@nonce" />
    </head>
    <body>
        <Routes />
    </body>
</html>

@code {
    [CascadingParameter] private HttpContext? HttpContext { get; set; }
}

data-theme on <html> is the kit's attribute: the switch, its script and the stylesheet read and write it. An app that sets its own data-theme there fights the switch; an app that wants a fixed theme sets the tokens instead (see Overriding the kit). After an enhanced navigation, and when the browser shows a page again from its back-forward cache, the script puts the page back in line with the cookie. A page rendered from the cookie differs from one viewer to the next, so it must not sit in a shared cache without Vary: Cookie.

The mark

KitMark renders the package's name and exact version. It belongs on signed-in pages, never an anonymous one: an exact version tells a scanner which advisories apply.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
10.4.0 0 11/20/2026
10.3.0 40 11/19/2026
10.2.0 48 11/18/2026
10.1.0 51 11/17/2026
10.0.0 57 11/16/2026

10.1.0: the settings screen, the package's first screen (Solhigson.Admin.Components, Solhigson.Admin.Settings, Solhigson.Admin.Auditing). KitSettingsEditor, which an app places on a page of its own with its route and [Permission], lists every setting the app's catalogue declares, one section a group in the order the catalogue registered them, under a Settings header that counts them and links to a needs-attention view, with a GET filter over key, name and purpose, never a value. CanEdit, false unless set, comes from a second permission: without it no form renders, a post is the framework's 400 and a Personal value shows as Hidden; a Secret's value is never written into the page. With it each line is a form of its own that saves or resets that setting through Core's SaveDeclaredSettingAsync and ResetDeclaredSettingAsync and says the outcome at the line: saved, reset, no change, a refusal beside the field in the screen's words with what was typed kept (never a secret's), changed since the page loaded, failed with no exception text, and a Warn alert when other instances were not told and may show the old value until their settings cache recovers. Under the groups, Rows with no declaration lists each stored row no declared setting matches, by name and flag pills, never a value; with CanEdit each has a Remove that opens one KitConfirm saying older code may still read the row by name and the screen cannot put it back, and its confirm calls RemoveUndeclaredRowAsync. Above the groups a warning says a secret's save is refused while the legacy encryptor is in force. The setting field: KitSettingField renders one KitSetting (KitSetting.From(DeclaredSettingLine)) with one control of its kind: a Switch a toggle that submits its form when it changes (a Save in noscript otherwise), a number with min, max and step, a Duration an amount and a unit or one text field, a List a textarea, a Text a text field; a Secret, a row stored sensitive and a masked line an empty password field, with no value or mask in the markup; with ReadOnly, Fields, Error and ChildContent. KitSettingValue.Compose turns the posted KitSettingFields into the setting's stored text or a refusal sentence (KitSettingComposed), never an exception, and Fill gives each control's starting values. The audit seam: IKitAudit (Records, and RecordAsync answering whether a row was written), which AddSolhigsonAdmin registers scoped as KitAudit<TContext>, resolving the audit service, the actor provider and the context from the request at first use; KitAuditEvent and KitAuditActions. Each save, reset and removal done is recorded as a SecurityEvent on AppSetting, settings.saved, settings.reset or settings.stray-removed, with the actor and a payload of the key and the values before and after as the framework's result shows them, the mask for a Secret, a row stored sensitive and a Personal value. A removed stray row stored plain under a plain name keeps its raw value in the append-only audit row: only a row stored sensitive or under a secret-looking name is masked. When Records is false (no audit service resolves, or the context maps no AuditTrail and no IAuditSink is registered) the screen says changes here leave no audit record and one Warning is logged a process; a record that fails logs one Error and says so at the line, and the change is not undone. TContext must be registered scoped. KitConfirm gains OnConfirm and KitDialog OnSubmit, so a confirm's form is handled by the component that owns it; kit.forms.js submits the form of a data-kit-submit-on-change control and keeps one such post in flight a page; the gallery gains a settings section; kit.manifest.json gains the kit-setting and kit-settings names. The README documents the app's page and every log line the screen, the seam and a save write. Minor bump: every type and member is new, and no existing component's behaviour changes. Depends on Solhigson.Framework.Core 10.27.0 or later. 10.0.0: the first release of Solhigson.Admin, the admin kit: Razor components for Solhigson apps, rendered statically on the server, with no interactive render mode and no inline script; an app owns every route, and the package holds components and no screen yet. Head and theme: KitHead, first in <head>, links the kit's stylesheet and scripts with the page's nonce where its policy uses one; KitTheme reads the viewer's light or dark choice from its cookie on the server, with KitTheme.HtmlAttributes(HttpContext) for <html>, and KitThemeSwitch offers the choice. Components: KitButton, KitStatusPill and KitAlert; KitField, one field for every input kind; KitDialog (a modal or a drawer) and KitConfirm on the native <dialog>; KitMenu, KitMenuItem and KitMenuForm, a row menu on the native popover; KitShell, the admin layout with a skip link, a side rail, a top bar with the user's menu (the theme choices and sign-out) and the main region; KitPageHeader, KitLead, KitEmptyState and KitPager; KitTable with KitColumn, and KitFilterBar, Get or Post; KitMark; and KitGallery, every component in every state on fixed example data, for a page an app adds in development or behind a permission. Links: every url a kit component takes goes through KitHref: a ~/ path is joined to the path base; a button's or a link menu item's Href may also be an https:// address (KitHref.LocalOrHttps), and a form's action is local alone (KitHref.Local). Menu: IKitMenuSource builds the shell's menu from the permissions the signed-in user's roles hold, read through PermissionManager's cached reads, and AddSolhigsonAdmin<TUser, TContext>() or AddSolhigsonAdmin<TUser, TKey, TContext>() registers it; the menu shows, each page's [Permission] enforces. Styles: tokens for every colour, size, space, radius, shadow, duration, curve and font, light and dark, in layers (kit.tokens, kit.base, kit.components) that an app's app layer overrides, each name listed in kit.manifest.json, a name leaving which is a breaking change; every motion reads a duration token that is 0ms under prefers-reduced-motion. Rules: the package's tests hold its markup, scripts and stylesheets to no inline script, style or handler, no other host, every href and form action through KitHref, measured contrast pairs, and no colour, length or duration outside the tokens. Depends on Solhigson.Framework.Core 10.24.0 or later.