feat(theme): implement accessible Technical-Light 1.0 contracts
This commit is contained in:
@@ -0,0 +1,153 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user