Refactor: Playersearch standardization — active/inactive/banned tiers, full surface conversion, Advanced Search

[baltinerdist]

Opened early for visibility/review. Reviewed separately from #476 (units work + standalone award-giver fix).

What this does

Replaces ~40 divergent player-search implementations (6 incompatible backend endpoints, jQuery-UI + bespoke dropdowns) with one standardized player search, then layers on a consistent active → inactive → banned result model and a rich Advanced Search page.

One core, one endpoint, one component

• One ranking core — SearchService::RankedPlayers(): concentric-ring ranking centered on the surface (Park → Kingdom → Everywhere), rank-don't-exclude by default, opt-in restrictTo / restrictKingdomIds / excludeKingdomId / excludeParkId / excludeIds. Kills the recurring "can't find people outside my kingdom" bug class.
• One canonical endpoint — SearchAjax/players (+ session-less SOAP Search/Players for testing), returning an envelope {rows, hasMore, offset}. The 6 legacy endpoints (KingdomAjax / ParkAjax / SearchAjax-universal / AdminAjax / EventAjax playersearch + SearchService::Player) delegate to the core so ranking can't drift again.
• One component — OrkPlayerSearch (custom dropdown, never jQuery UI; fixed-position for modals; dark-mode; ARIA combobox; excludeIds / reattach / preload / onClear), loaded app-wide.

Active / inactive / banned result model (new)

Every surface now returns three tiers in one consistent order:

• Active first, then Inactive as a last resort (always shown, ranked after all active).
• Banned (suspended OR penalty_box) shown only to viewers with CREATE/EDIT authority relevant to the surface, and scoped one level up: a park surface surfaces the kingdom's banned players; a kingdom / global / universal surface surfaces Amtgard-wide bans. Plain users never see banned players anywhere.
• restrictTo:'kingdom' is now principality-family-aware (a "within kingdom" / kingdom-merge search still finds principality members).
• Distinct Banned (red) / Suspended (amber) / Inactive (gray) badges; inactive rows dimmed, banned rows tinted; dark-mode aware.

Advanced Search page (new)

A full-page power-search at Search/advanced, opened in a new tab from the inline component's split Load more… | …or Advanced Search footer (carrying the typed term + current scope):

• Filters: Active / Inactive toggles, officer-gated Banned (Amtgard-wide), kingdom→park cascade, optional last-attendance date range.
• Results render as a DataTable (Reports styling): zebra striping, pagination, "Show N rows" / "Showing X–Y of N", sortable headers, responsive (no horizontal scrollbar on desktop, columns collapse on mobile).
• Columns: persona, real name (officers only; a restricted player's real name is admin-only), home kingdom/park, last-attendance kingdom/park + date, status pill, link-out, and a copy-Player-ID button (instant CSS tooltip "Copy Player ID - Paste this into your search!").
• Kingdom names are shortened in-cell ("The Kingdom of the Wetlands" → Wetlands).
• Paste-an-ID flow: a pure-numeric query (in the inline component or Advanced Search) is a direct mundane_id lookup — copy an id here, paste it into any player search.

Surfaces converted (~40 call sites)

Award giver/recipient, attendance (kingdom / park / event + the Parknew sign-in modal with its scope toggle, already-attended exclusion, and inactive-reactivation confirm), recommendations, Move Player (Kingdom / Park / Admin — mode-driven exclude/restrict + cascade re-scope), Merge (cross-field exclude; kingdom merge now restrictTo:'kingdom'), Unit add member/manager (intentionally global), officer / permission grants (scoped + global), reconcile, Edit Officers (Kingdom + Park), and the universal header search.

Security

mysql_real_escape_string is a no-op polyfill in this codebase, so player/term LIKE interpolation was unescaped (SQL-injectable). Replaced every term interpolation in RankedPlayers, the legacy Player(), and the Event/Kingdom/Park name searches with a real likeEscape() (quote-doubling + % _ \ escaping). Banned-visibility and restricted-real-name gating are enforced server-side from the session token — client params can't widen them.

Surface bug fixes & cleanup

• Award "Given At" handler no longer wipes the selected recipient id.
• Reports_roster "Suspended By" passes the correct entity for park-scoped rosters.
• Admin Move Player "current park" select re-scopes the search; Attendance re-scopes on kingdom/park change.
• Removed dead #PlayerSearch jQuery-UI bindings and the superseded EventAjax/AdminAjax playersearch endpoints.

Testing

• tests/playersearch/banned_matrix.sh — authenticated full matrix (active/inactive/banned × park/kingdom/global × anon/plain/officer/admin), 15/15 green; tests/playersearch/ranking.sh 12/12.
• tests/playersearch/chrome-matrix-protocol.md — full in-Chrome test protocol.
• Verified live in Chrome (dark mode): one-level-up banned scoping, attendance scope toggle, Move Player context, the Advanced Search DataTable, and the inline → Advanced Search → paste-ID round-trip.

Notes for review

• Banned players are shown AND selectable on every surface (product decision) — rows are badged but not blocked; server-side operations still enforce their own rules.
• Legacy default-template admin pages (Set Officers, Authorization, Event, Audit Log, the public Search page) are out of scope here (not part of the 3.5.x design language).
• The newly-unused KingdomAjax/ParkAjax playersearch endpoints were left in place (harmless) now that move-player routes through SearchAjax/players.

🤖 Generated with Claude Code

[baltinerdist]

Branch brought current with master

Synced up to master @ 6ab028a3 (merge commit 363fe869). This branch was 523 commits behind; now 0 behind / 35 ahead.

The core collision

Upstream's R-11: "Consolidate search and player search in SearchService domain" did the same consolidation this branch did — differently. Upstream moved the legacy per-controller SQL into SearchService::UniversalSearch/ScopedPlayerSearch; this branch moved it into SearchService::RankedPlayers/AdvancedPlayers with the 3-tier model.

Both satisfy the "DB work in system/lib/ork3/" intent, so the resolution kept upstream's structure and made this branch's RankedPlayers the engine behind it.

Conflicts: 12 files

File	Resolution
class.SearchService.php (12 hunks)	Kept both method sets — no name collisions. Took upstream for Event() draft-status/event_type/banner fields. Kept this branch's likeEscape()/(int)-cast SQLi fixes over upstream's no-op mysql_real_escape_string. Merged upstream's unset($_SESSION['is_authorized_mundane_id']) fix in. Then rewired UniversalSearch()'s player block to delegate to RankedPlayers so header search keeps the tier model.
controller.SearchAjax.php	universal() → upstream's Model_Search::universal_search pass-through + 'Token'; kept this branch's new players() and advanced() endpoints verbatim.
controller.Search.php	Upstream's $this->Authorization->has_authority + get_unit_activity_counts delegation; kept this branch's advanced() action.
controller.AdminAjax.php	Kept the branch's retirement of global/playersearch; took upstream's model-based add_auth + audit and AdminDashboard delegation.
controller.KingdomAjax.php (23 hunks)	All upstream, then re-applied this branch's playersearch body (RankedPlayers with family-kingdom restrictKingdomIds for scope=own, excludeKingdomId for scope=exclude).
controller.ParkAjax.php (11 hunks)	Same pattern — upstream everywhere, branch's RankedPlayers body restored (restrictTo:'park' / excludeParkId).
controller.Admin/Player/Kingdom/Park.php	Git mis-aligned these (branch tab-indented vs upstream PSR-12). Took upstream wholesale, then re-applied the branch's officer role-case fix (strtolower(...) + ucwords(str_replace('_',' ',...))) to every PreloadOfficers block — 6 in Player, 2 each in Admin/Park, 1 in Kingdom.
revised.js	Took the branch's OrkPlayerSearch.attach conversion for the Event-attendance field; upstream's side would have reintroduced a hand-rolled multi-fetch kn-ac- dropdown. Verified no orphaned evPn* helpers remain.
controller.EventAjax.php	All upstream (EventPlanning refactor, staff/schedule, draft status).

Feature integrity — independently re-verified post-push

• ✅ Award "Given By" giver stays GLOBAL. All three sites (pn-/kn-/pk-award-givenby-text) carry no restrictTo key — only kingdomId/parkId as ranking centre. Every restrictTo in revised.js belongs to a Move/Merge Player field, where scoping is correct.
• ✅ Unit member add stays GLOBAL — unAttachPlayerSearch passes parkId/kingdomId as ranking centre only, no restrictTo.
• ✅ 18 OrkPlayerSearch.attach + 3 reattach sites byte-identical to the branch tip; all 19 template call sites survive; ork-player-search.js/.css still loaded globally in default.theme; Search_advanced.tpl intact.
• ✅ No jQuery UI autocomplete on any player field. The two remaining .autocomplete() calls are knWireParkAutocomplete (Park search) and the parent-kingdom search — both pre-existing non-player fields.
• RankedPlayers output is a superset of the legacy row shape (MundaneId/Persona/KAbbr/PAbbr + tier fields), so surviving legacy callers stay compatible.

Verification: no conflict markers; php -l clean on all 308 changed .php/.tpl/.theme; node --check OK on revised.js and ork-player-search.js; class.Authorization.php unchanged vs branch tip, no bypass. Merge recomputed from its parents with rerere disabled and diffed against what was pushed — exactly the 12 conflicted files, nothing unexplained. (Two other branches in this batch were contaminated by a stray line from an unrelated rerere resolution; this one is clean.)

For a human

1. ⚠️ Upstream's playersearch endpoints were kept in KingdomAjax, ParkAjax, and EventAjax, against this branch's retirement of them. Upstream's new Event Staff / Schedule Leads feature (added after the branch point) calls KingdomAjax/playersearch in 4 places in revised.js — dropping the endpoint would have broken new upstream functionality. The Kingdom/Park ones now run through RankedPlayers; EventAjax's still runs through upstream's ScopedPlayerSearch.
2. Two new upstream surfaces are unconverted — the Event Staff name field and the Schedule Leads field still use hand-rolled kn-ac- dropdowns with tnPositionAcFixed. They work, but they fall outside the standardization this PR claims. Worth a follow-up commit here.
3. ScopedPlayerSearch + parkOrderClause + formatScopedPlayerRow are now only used by EventAjax. Upstream code wasn't deleted during a merge; worth deciding whether to converge EventAjax onto RankedPlayers and drop them.
4. UniversalSearch no longer uses its $includeInactive/$callerUserId/$fold locals for the player query (tier logic moved into RankedPlayers). Harmless, but a linter may flag the unused assignments.

PR now shows MERGEABLE / CLEAN.

🤖 Generated with Claude Code

[baltinerdist]

Follow-up: Event Staff and Schedule Leads converted (18118780)

Closes the standardization gap flagged above. Both surfaces now use OrkPlayerSearch, bringing the branch to 20 attach sites (was 18) with zero remaining KingdomAjax/playersearch calls in revised.js.

Event Staff (#ev-staff-player-name / hidden #ev-staff-player-id) and Schedule Leads (#ev-sched-lead-input, chips in evSchedLeads[]) both previously ran the same hand-rolled pattern: KingdomAjax/playersearch/{kingdomId}&q=…&scope=own, then — if fewer than 5 hits — a second &scope=exclude fetch appended and deduped to top up to 10, with a global SearchService.php fallback when the event had no kingdom.

Scope is preserved exactly. That old behavior was kingdom-ranked, not kingdom-restricted, so neither attach carries restrictTo — parkId/kingdomId act as ring centre only. Independently confirmed on the pushed branch: no restrictTo key on either new call site, and the no-kingdom case still degrades to a global search (both ids resolve to 0). Neither field became global, and neither previously-scoped field was narrowed.

Three deliberate deltas, all recorded in the commit body:

• parkId joins the ring centre — the old endpoint had no park notion. Ranking only; it cannot widen or narrow the result set.
• Schedule Leads gains excludeIds so already-chosen leads stop appearing.
• Adding a lead by search now calls evRefreshStaffQuickAdd(), matching what the + Add and remove paths already did.

Both match the attendance search already on this page (ev-PlayerName).

Modal positioning. Both fields sit inside modals (#ev-staff-modal, #ev-schedule-modal, overflow-y:auto). The old code hand-set position:fixed; z-index:9999 and called tnPositionAcFixed on every render. OrkPlayerSearch handles this internally — it appends .ops-ac-results to document.body, sets position:fixed in its own position(), reflows on scroll/resize/visualViewport, and carries z-index:2147483000. It also stopPropagation()s Escape while open, so dismissing the dropdown no longer closes the whole modal. No tnFixedAcPosition call is needed for these two.

Dead code removed, with grep proof: the #ev-staff-ac / #ev-sched-lead-ac divs, evStaffAcTimer, evSchedLeadAcTimer, OPEN_CLASS, ITEM_SEL, and the render/position/blur/focusout handlers — all zero remaining references (re-verified post-push). Also removed gid('ev-staff-ac').classList.remove('kn-ac-open') from evOpenStaffModal, which would have thrown once the div was gone.

Kept because they still have live callers: escHtmlSt (3 callers), acKeyNav (4 call sites), tnPositionAcFixed (4 call sites including park search).

Verification: node --check passes; 20 attach sites; php -l clean on the template. The only two remaining .autocomplete() calls are the pre-existing non-player searches — knWireParkAutocomplete (line 4152) and the parent-kingdom search (line 5823) — so no player field regressed to jQuery UI.

Not runtime-tested — no browser check of dropdown rendering inside ev-staff-modal / ev-schedule-modal. Worth a click before merge, since modal positioning is the one thing static analysis can't confirm.

🤖 Generated with Claude Code