Skip to content

UIGuide_getClanTournamentPlayers.md

Latest commit

 

History

History
140 lines (111 loc) · 5.9 KB

UIGuide_getClanTournamentPlayers.md

File metadata and controls

140 lines (111 loc) · 5.9 KB
Raw

UI Guide — getClanTournamentPlayers

Overview

  • Powers the clan drill-down modal opened from a clan row on the tournament detail's clan leaderboard tab (see getTournamentInstanceInfo).
  • One-shot fetch. No cache, no polling, no subscription. Re-call to refresh.
  • Returns up to ~20 players, server-sorted by score DESC. Client-side re-sort is unnecessary.

Modal / drawer layout

Top-to-bottom layout (centered modal on desktop, full-screen slide-up sheet on mobile):

  1. Close affordance — explicit close button (top-right); click-outside dismiss; Escape key dismiss.

  2. Clan header — clan image (1:1 aspect ratio, fallback to first-letter avatar with the clan's name), clan name, total score, contributing-members count, and a rank badge (1/2/3) if applicable.

    The default Smartico UI populates this header from the caller-side ClanLeaderboardEntry object (the row the user clicked) rather than from the response's clan_public_meta and clan_id — they contain the same identity but the parent context already has richer data (total_score, contributing_members, position) that the response doesn't carry. The response's clan_id and clan_public_meta.name/image_url are still available for consumers that need them.

  3. Table header row — three columns: # (rank) · Player (avatar + name) · Score.

  4. Player list — one row per players[i]. See "Player row".

  5. Empty state (when players.length === 0) — "No leaders" text. Shown both during the loading round-trip AND when the result is empty.

Player row

Three columns:

Column Source Notes
# (rank) position ?? 0 Plain text. Server-side rank within this clan.
Player (avatar + name) avatar_url (or derived from avatar_id + label avatarDomain) + clean_ext_user_id ?? public_username Username prefers clean_ext_user_id over public_username; if both empty, the avatar fallback letter is also blank.
Score scores ?? 0 Format with space-thousands ("1 234 567") + "pts" suffix.

"Me" row highlight: when is_me === true, add a distinct background (CSS class is-me in the default Smartico UI). There is no sticky "me" footer in this modal — the user's row scrolls with the list. If your UI has many players (rare — server caps at ~20), you may want to auto-scroll the "me" row into view on first render.

Avatar resolution: if avatar_url is already populated by the SDK, use it directly. Otherwise, derive a CDN URL from avatar_id and the brand's avatar domain — the SDK's CoreUtils.avatarUrl() does this for you on the response.

Top-3 styling: optional — apply podium accent (gold/silver/bronze) to rows where position <= 3. The default Smartico UI applies the podium treatment only on the clan header rank badge, not on individual player rows.

Empty / loading / error states

  • Loading: render the modal frame and clan header immediately (driven by caller-side data); render an "empty state" placeholder in the player list area while the call is in flight. Or render a skeleton rows (3–5 grey bars) — typically friendlier than the empty-state text appearing then disappearing.

  • Empty (no players): render the "No leaders" text. This can mean:

    • no one in the clan has scored yet,
    • the call failed (network / server error — the default UI silently swallows the error),
    • the (tournamentInstanceId, clanId) combination is invalid.

    These three are not distinguishable in the response itself. The default UI treats them identically. If your UI cares to distinguish, attach a .catch() to surface a transient-error toast.

  • Error: not surfaced by default. Add explicit error handling if needed — wrap the call in try/catch and show a "Failed to load — Try again" affordance.

Close affordance

Three independent dismiss mechanisms (all dispatch the same close action):

  1. Close button (top-right of modal).
  2. Click outside the modal card.
  3. Escape key.

The default Smartico UI wires all three via a shared useModalClose hook. Mirror this pattern for parity.

Refresh

  • Don't poll inside this modal. The default Smartico UI doesn't poll — the clan-leaderboard tab (parent) does poll via getTournamentInstanceInfo and refreshes the visible clan rankings when the modal closes. Live updates inside the modal are not part of the default UX.
  • If your product requires live updates inside this modal, call getClanTournamentPlayers again on a 3 s interval. Be cautious — each call is a fresh network round-trip (no cache).

Pagination

None at the SDK level. The server returns up to ~20 players (configured per tournament). There is no "load more" affordance in the default UI.

Animations / transitions

  • Modal entry: fade-in + scale (~150 ms ease-out).
  • Modal exit: fade-out + scale-down (~120 ms).
  • List entry: cards/rows fade-in staggered ~20 ms per row on first render. No skeleton-to-data crossfade (the list is small enough to render instantly once data arrives).
  • Rank change between calls (if you implement live polling): FLIP animation to reorder rows.

Mobile vs desktop

  • Modal style: centered overlay on desktop with backdrop dim; full-screen slide-up sheet on mobile (with a swipe-down dismiss gesture).
  • Header layout: image left, identity right on desktop; stacked (image above identity) on mobile.
  • Row density: identical on both — the row is already compact.

Performance

  • Each call is a fresh network round-trip. The page typically has at most one of these in flight at a time (driven by user clicks), so cost is minimal.
  • If your UI offers a "view all clans" affordance that pre-fetches player lists for many clans, throttle the fetches — don't fan out 20 simultaneous round-trips.