Turfi Platform Documentation

Operational trust depends on the platform clearly communicating when work is happening. This document exists to capture the shared interaction rules that keep Turfi responsive and understandable during asynchronous actions. It fits across every workspace because loading behavior, request tracking, and interaction feedback are platform-wide concerns. As Turfi matures, this file should remain the guide for system-level UX consistency.

Shared status legend: [docs/_shared/status-legend.md](./_shared/status-legend.md)

---

Global Async Activity System

Long-running operations can make the platform appear frozen even when work is still running. Turfi therefore tracks shared request activity through an activeRequests counter.

Behavior:

• Request starts -> activeRequests++
• Request finishes -> activeRequests--
• If activeRequests > 0, a global activity indicator appears in the top toolbar

Optional enhancement:

• thin progress bar under the header

Button Loading Behavior

Async UI buttons must:

• disable during execution
• show a spinner
• update text to indicate action

Examples:

• Preview -> Previewing
• Load -> Loading
• Execute -> Executing

Shared Loading Button Component

Turfi uses a reusable button component that supports a loading state.

Example concept:

• <Button loading>

Loading state automatically:

• shows spinner
• disables button
• updates text

Async Request Wrapper

Turfi uses a shared wrapper so async operations consistently participate in the global activity system.

Example concept:

• trackedRequest()

Example:

await trackedRequest(() =>
  supabase.from("players").select()
);

All async API calls should pass through this wrapper.