# 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
Clear filter
@Visible.Count matching instances
@foreach (var name in Visible) {
@name
}
@code {
private string Filter = "";
private readonly string[] Names = ["Fixture A", "Fixture B"];
private List 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
@code {
private sealed record Observation(int Id, string Name, DateTimeOffset UpdatedUtc, string Detail);
private readonly List _rows = [];
private readonly HashSet _expanded = [];
private bool _ascending = true;
private IEnumerable 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.