8.3 KiB
Shared interaction recipes
These patterns accompany the 1.0.0 Theme candidate. The host owns domain state, authorization, validation, sorting, filtering and asynchronous outcomes. Examples are local adapters, not new generic Theme components. Preserve supported SSR login POST, antiforgery and safe return URL behavior.
Label a filter and give it a clear action
<label for="instance-filter" class="form-label">Filter instances</label>
<div class="d-flex gap-2">
<input id="instance-filter" class="form-control" type="search"
@bind="Filter" @bind:event="oninput" aria-controls="instance-results" />
<TechButton Variant="ButtonVariant.Secondary" @onclick="Clear"
disabled="@(Filter.Length == 0)">Clear filter</TechButton>
</div>
<p id="instance-count" role="status">@Visible.Count matching instances</p>
<ul id="instance-results" aria-describedby="instance-count">
@foreach (var name in Visible) { <li @key="name">@name</li> }
</ul>
@code {
private string Filter = "";
private readonly string[] Names = ["Fixture A", "Fixture B"];
private List<string> Visible => Names.Where(n =>
n.Contains(Filter, StringComparison.OrdinalIgnoreCase)).ToList();
private void Clear() => Filter = "";
}
The names above are illustrative fixture data. Each actual page filters its displayed dataset, preserves selection by stable identity, and explains if search covers only loaded branches. Announce user-requested count changes politely; do not put all polling values in a live region. Placeholder text supplements a visible label.
Keep tables semantic and locally scrollable
<div class="table-wrap" role="region" aria-label="Instance observations" tabindex="0">
<table class="data-table">
<caption>Latest observations, timestamps in UTC</caption>
<thead><tr>
<th scope="col">Instance</th>
<th scope="col" aria-sort="@(_ascending ? "ascending" : "descending")">
<button type="button" @onclick="ToggleSort">Updated (UTC)</button>
</th>
<th scope="col">Details</th>
</tr></thead>
<tbody>
@foreach (var row in Ordered)
{
<tr @key="row.Id">
<th scope="row">@row.Name</th>
<td class="mono">@row.UpdatedUtc.ToString("yyyy-MM-dd HH:mm:ss 'UTC'",
System.Globalization.CultureInfo.InvariantCulture)</td>
<td><button type="button" aria-expanded="@(_expanded.Contains(row.Id) ? "true" : "false")"
aria-controls="@($"detail-{row.Id}")" @onclick="() => Toggle(row.Id)">
@(_expanded.Contains(row.Id) ? "Hide" : "Show") details for @row.Name
</button></td>
</tr>
<tr id="@($"detail-{row.Id}")" hidden="@(!_expanded.Contains(row.Id))">
<td colspan="3">@row.Detail</td>
</tr>
}
</tbody>
</table>
</div>
@code {
private sealed record Observation(int Id, string Name, DateTimeOffset UpdatedUtc, string Detail);
private readonly List<Observation> _rows = [];
private readonly HashSet<int> _expanded = [];
private bool _ascending = true;
private IEnumerable<Observation> Ordered => _ascending
? _rows.OrderBy(r => r.UpdatedUtc).ThenBy(r => r.Id)
: _rows.OrderByDescending(r => r.UpdatedUtc).ThenBy(r => r.Id);
private void ToggleSort() => _ascending = !_ascending;
private void Toggle(int id) { if (!_expanded.Add(id)) _expanded.Remove(id); }
}
A sort cursor alone does not sort. Use a real button and update the displayed order;
keep aria-sort on the applicable header. Retain precision required by the domain
(BTDB uses seven fractional digits) rather than copying the illustrative format above.
Disclosure is a keyboard-operable button, not a clickable row; its expanded state and
controlled region must agree. TreeTable remains caller-owned and stateless. Give each
scroll region a meaningful name and visible focus; document width stays bounded while
tables scroll inside it. Long identifiers wrap in cells unless precision demands a
horizontal pane. Keep action names contextual and preserve role gates.
Distinguish empty, failed, pending and stale
- Initial load: say what is loading; show a stable layout and skeleton where useful.
- No data: explain what the user can create or connect, subject to authorization.
- No matches: state that the filter excluded results and provide Clear filter.
- Failed request: name the failed operation and a valid Retry action; do not report success, zero results or healthy status from an absent observation.
- Stale observation: retain the last known data, label it stale, show its observed UTC timestamp and age, and distinguish observation age from current reachability.
- Pending observation: display Pending/Unknown explicitly; do not infer Offline.
Render a persistent inline status region for user-initiated operation outcomes. Put a
validation summary near the form and associate errors with their inputs through
TechField's For/HintId/ErrorId contract. Use aria-invalid only when invalid. The form
owns focus on the first relevant invalid control after submission. Keep status labels
readable and textual alongside optional signal dots; color alone is insufficient.
Never announce secret values, every background refresh or every connection heartbeat.
Busy actions and safe confirmation
A busy TechButton shows BusyText and aria-busy, keeps caller-disabled semantics,
and restores its ordinary label afterward. The host publishes success/failure in its
separate outcome region and keeps recovery available. Preserve focus after completion;
a disabled action is not a replacement for explaining why the user cannot proceed.
Use confirmation only for work that warrants interruption and protected focus. For ordinary editing prefer inline controls or a dedicated page. Reuse the host's existing strong dialog implementation; there is no generic Theme modal in this release.
A conforming dialog adapter must:
- Capture the connected trigger before opening. Associate a visible heading and
description through
aria-labelledby/aria-describedby, and use modal semantics. - Mount outside transformed/animated clipping ancestors. Lock background interaction (inert) and scroll while maintaining an intentional nested-overlay policy.
- Move focus to the safe action or relevant initial control. Bind a native DOM keydown
listener to the actual event. Tab/Shift+Tab stay within visible, enabled, non-inert
controls; call
preventDefault()synchronously at boundaries. With no focusable child, focus the dialog container. Never readwindow.eventafter async interop. - Escape closes only when safe. During irreversible/busy work, follow the operation's explicit cancellation rules; do not imply that closing cancels server work.
- Remove listeners/inert/scroll locks on close and disposal. Restore focus once to a still-connected trigger, or a stable page heading when it disappeared. Do not keep one global saved element for independently nested dialogs.
- Verify with real keyboard input: forward/backward boundaries, hidden/disabled controls, Escape, failed request, busy-close rules and disconnected-trigger fallback.
Native dialog is an option after the host/browser suitability check; its presence alone
is not proof of lifecycle correctness. A reusable extraction decision waits for two
successful consumer pilots (G2), with browser contract tests in both host modes.
Focus, motion and viewport acceptance
Focus must be visibly distinct from selection across all approved accent families,
including scroll regions and custom controls. Preserve stronger specialized focus
rules. Reduced-motion users see .rise content in its final state immediately and a
stable connection signal; text still communicates the state. Do not globally force
all animations to 0.01ms.
Verify desktop 1440×900, tablet 1024×768, phone 390×844, actual browser 200% zoom, keyboard and reduced motion in one bounded inspection round, then one confirmation round after fixes. Check mobile navigation open and closed, local table scrolling, reachable actions and the supported dark scheme. Screenshot and token math do not replace actual computed styles, DOM focus movement and user interactions.