Solhigson.Admin
10.0.0
See the version list below for details.
dotnet add package Solhigson.Admin --version 10.0.0
NuGet\Install-Package Solhigson.Admin -Version 10.0.0
<PackageReference Include="Solhigson.Admin" Version="10.0.0" />
<PackageVersion Include="Solhigson.Admin" Version="10.0.0" />
<PackageReference Include="Solhigson.Admin" />
paket add Solhigson.Admin --version 10.0.0
#r "nuget: Solhigson.Admin, 10.0.0"
#:package Solhigson.Admin@10.0.0
#addin nuget:?package=Solhigson.Admin&version=10.0.0
#tool nuget:?package=Solhigson.Admin&version=10.0.0
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:
- 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-inksets--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-dangersets--kit-state-danger-hoverlikewise. The focus ring is black (white in dark) and stays so: an app re-inking the kit decides--kit-focusitself. - A component token, such as
--kit-mark-gapor--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:rootor on the component. - 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 byforandid; the hint and the error describe it byaria-describedby. - An
Errormarks the controlaria-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. Requiredputsrequiredon the control and a visible mark in the label, read as "(required)".- The id is
kit-field-and theName, every character that is not an ASCII letter or digit written as_and its four hex digits (Items[0].Nameiskit-field-Items_005B0_005D_002EName). It is the same on every render and different for every other name. Two fields of oneNameon one page, in two forms, each need their ownId. - A
Passwordnever writesValueinto the page, so a stored secret shows only as set or not set; it carriesautocomplete="new-password"unlessAutoCompletesays otherwise, since browsers ignoreoffon a password and would fill the administrator's own saved password. - A
Selecttakes itsOptionsas value and text pairs, in order; the option whose value equalsValue, compared ordinally, is selected.Placeholderadds a first, empty option, chosen whenValueis empty. Min,MaxandStepare aNumber's or aDate's;ReadOnlyis an input's or a textarea's, since a browser lets a select, a checkbox and a toggle change though they are read-only (useDisabled). A parameter the kind cannot honour is refused with an exception, as areOptionson any kind but aSelect.- Every other attribute lands on the control. The field owns
id,name,required,disabledandaria-invalidon every control;type,value,placeholder,min,max,step,readonlyandautocompleteon an input;placeholder,readonlyandautocompleteon a textarea;autocompleteon a select;type,valueandcheckedon a box or a toggle; androleon a toggle. It writes them after the caller's, so a passed one is replaced; set them through the parameters. A passedclassand a passedaria-describedbyjoin the field's own. A url attribute is refused, asKitButtonrefuses 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.
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.
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,
HrefthroughKitHref.LocalOrHttps; - a dialog opener,
OpenDialognaming aKitDialogorKitConfirm, with itsdata-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
KitMenuFormof itsFormName(form=) to its ownAction(formaction=, throughKitHref.Local), with thenameandvaluewritten on the item: the pressed row's value alone is posted; - a theme choice,
ThemeChoicelight,darkorsystem, arole="menuitemradio"thatkit.theme.jsswitches as it switches aKitThemeSwitchchoice,aria-checkedon 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, scoped, 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 gallery
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.
Links
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 | Versions 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. |
-
net10.0
- Solhigson.Framework.Core (>= 10.24.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
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.