154 lines
8.3 KiB
Markdown
154 lines
8.3 KiB
Markdown
# 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
|
||
|
||
```razor
|
||
<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
|
||
|
||
```razor
|
||
<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:
|
||
|
||
1. Capture the connected trigger before opening. Associate a visible heading and
|
||
description through `aria-labelledby`/`aria-describedby`, and use modal semantics.
|
||
2. Mount outside transformed/animated clipping ancestors. Lock background interaction
|
||
(inert) and scroll while maintaining an intentional nested-overlay policy.
|
||
3. 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 read `window.event` after async interop.
|
||
4. Escape closes only when safe. During irreversible/busy work, follow the operation's
|
||
explicit cancellation rules; do not imply that closing cancels server work.
|
||
5. 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.
|
||
6. 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.
|