Drag-to-reorder organizations in the org list and switcher

[bdunncompany]

Drag-to-reorder organizations in the org list and switcher

Why

On /settings/organizations and the top-bar org switcher, organizations come back in an implicit order (creation timestamp). For an MSP, that order doesn't match how often you actually touch each customer. The customers you work with most often are the ones you most want at the top of the dropdown, but they're often the ones who were onboarded recently — so they end up at the bottom.

Drag-to-reorder, persisted partner-wide, fixes that with no other configuration burden.

What I built

A working POC running on a real MSP install. Behavior:

Before	After
List ordered by createdAt, can't change	Drag rows in /settings/organizations, order persists, top-bar switcher (Cmd+O) reflects it on next reload

Implementation summary:

• Persistence: partners.settings.organizationOrder?: string[]. No schema change — just a new key in the existing partners.settings jsonb. Mirrors the existing inheritable-settings pattern.
• API: new PATCH /orgs/organizations/reorder (partner scope, audited as partner.organizationOrder.update), body { orderedIds: string[] }. Idempotent; the request fully replaces the order. Server-side sanitization drops any IDs that aren't in the caller's accessibleOrgIds so cross-partner mischief isn't possible.
• Read path: GET /orgs/organizations applies applyOrganizationOrder() after the existing createdAt SQL sort, only for partner scope (and system scope when a partnerId filter is set). Unknown / newly-created orgs append at the end. If the partner-settings lookup throws for any reason, the response soft-falls-back to the createdAt order.
• UI: HTML5 native drag-and-drop in OrganizationsPage.tsx with optimistic update, revert-on-PATCH-failure via re-fetch. 6-dot grip handle visible on row hover. Drag is disabled while a search filter is active so users can't reorder a hidden subset.
• Both surfaces inherit the order automatically — the settings page list and the top-bar OrgSwitcher both consume GET /orgs/organizations, so server-side ordering is enough.

Why schema-free instead of an organizations.sort_order INTEGER column

I considered both. The settings-jsonb approach won for this POC because:

1. No migration. The change is reversible by removing one key.
2. It mirrors the existing partners.settings shape, so reviewers don't have to learn a new pattern.
3. Flexibility: dropping in users.settings.organizationOrder later (per-user override) is a one-line change.

A sort_order INTEGER column has real merits — index-friendly, lets the DB do the sort, conceptually cleaner. Happy to switch to that approach before any PR if you'd prefer it.

Tests

• 14 unit tests on applyOrganizationOrder / sanitizeOrganizationOrder (empty/null/duplicate/stale/single-org/no-mutation).
• 6 route tests on PATCH /orgs/organizations/reorder (happy path, drops unknown IDs, preserves unrelated settings keys, scope rejection, zod validation).
• Full API suite: 4084/4084 pass (28 skipped, 0 failed).
• Full shared suite: 551/551 pass.
• Web suite: pre-existing store-test failures only; nothing new from these changes.

Known gaps / open questions

Worth flagging up front:

• Touch / mobile: HTML5 native DnD doesn't fire on touch. Workable for the partner-side admin use case, but a mobile-friendly handle (long-press + arrow buttons, or a dedicated react-dnd-touch-backend swap) would be a nice follow-up.
• Keyboard accessibility: no arrow-key reorder yet. Real a11y gap; easy follow-up.
• Concurrency: read-modify-write with no transaction guard. Two simultaneous reorders by different staff are last-write-wins. Acceptable since reorder is rare and partner-scoped, but documenting it.
• Scope: requireScope('partner') only. System-scoped admins reordering on a partner's behalf would need an additional code path; happy to add if it's wanted.
• Per-user vs per-partner: the POC is per-partner ("most-used customers at the top, for the whole shop"). Per-user (users.settings.organizationOrder) is the obvious follow-up if multiple staff want different orderings.

Patches

Two patches against latest main:

1. Drag-to-reorder organizations on the settings page — types + API + helper + UI
2. test(api): cover PATCH /orgs/organizations/reorder endpoint — route tests

Happy to open a PR if there's interest, or to first switch to the column-based persistence path if you'd rather have that.

[ToddHebebrand]

Shipped in #681 — thanks for the well-scoped POC and the partner-settings-jsonb decision write-up, that made review easy. Closing as resolved.