Add a command palette for searching models, records and commands

[vahidzhe]

Adds a command palette to the admin: a modal that searches registered models,
records inside them, and commands, from any page.

Why

Finding a specific record today means picking the right model from the sidebar,
loading its list page, then searching within it. On an admin with a few dozen
models that is three steps and two page loads for something the user could name
immediately.

How it works

The palette answers three questions and each has a deliberately different cost.

Model names are matched against the in-memory view registry. No database
access, so this stays instant regardless of how many models are registered.

Records in one model are searched after clicking Search inside on a row,
which pins that model as the scope. Exactly one query runs against exactly one
model, again independent of how many exist.

Records across models are searched when typing without a scope. This is the
only mode that fans out, so it is opt-in per model, capped, and skipped entirely
for terms shorter than palette_search_min_chars.

class UserAdmin(ModelView, model=User):
    column_searchable_list = [User.name, User.email]
    palette_search = True        # joins the unscoped search
    palette_search_limit = 5     # rows returned per model

palette_search defaults to False. Adding the palette to an existing admin
therefore changes nothing about query load until a maintainer opts a model in.
Models that are not opted in remain reachable through Search inside, since
scoping is an explicit user action costing a single query.

Admin takes palette_search_min_chars (default 2) and
palette_search_max_models (default 8). Queries run concurrently on async
engines; sync engines go through the existing worker-thread path.

Scoped search

Clicking Search inside pins a model. The chip's × clears it.

Commands

Below the matches, the palette offers commands for the best-matching model.
With an empty box no commands are shown, since there is no match to act on.
ModelView.palette_commands returns them and can be overridden:

def palette_commands(self, request: Request) -> list[dict]:
    commands = super().palette_commands(request)
    commands.append(
        {
            "label": "Export users as CSV",
            "url": str(
                request.url_for(
                    "admin:export", identity=self.identity, export_type="csv"
                )
            ),
            "icon": "↓",
            "badge": "csv",
        }
    )
    return commands

Permissions

The palette exposes nothing the rest of the admin would not:

Rule	Effect
is_visible / is_accessible	view is not listed, not searched, 404 if named as a scope
check_can_view_details	rows the user cannot open never appear in results
can_view_details = False	model is skipped, there is nothing to navigate to
can_create = False	no "create" command
login_required	the endpoint sits behind the same guard as every admin route

How it renders in each configuration

The trigger lives in the top bar. That bar previously only rendered when a
language switcher was configured, so this PR makes the <header>
unconditional and leaves the switcher itself conditional. All four combinations
were checked:

i18n_config	authentication_backend	Top bar contains
set	set	trigger, language switcher
set	unset	trigger, language switcher
unset	set	trigger
unset	unset	trigger

Translations

Every string is translated, including those rendered by JavaScript as results
come in. 19 new strings were added to the az, de, ru and tr catalogs
(71/71 for each).

Strings that interpolate a model name are whole sentences with placeholders
rather than concatenated fragments, so word order stays translatable:

"Go to {name}"       ->  az: "{name} səhifəsinə keç"
                         de: "Zu {name} wechseln"
"Records in {name}"  ->  az: "{name} içindəki qeydlər"

Braces rather than %(name)s: Jinja's gettext treats %(...)s as its own
interpolation and raises KeyError when the variable is not supplied at render
time, which is the case here since substitution happens in the browser.

[mmzeynalli]

This func escapes for element content, not for attribute values. $("

").text(v).html() is Element.innerHTML over a text node, and the HTML serialization algorithm for that context only replaces &, <, > and U+00A0 — " is preserved verbatim.

[mmzeynalli]

class Doc(Base):
    slug = Column(String(200), primary_key=True)   # user-suppliable slug
    title = Column(String(80))

s.add(Doc(slug='x" tabindex=0 autofocus onfocus=window.__pwned=1 y="',
          title="quarterly report"))

Endpoint:

{"pk": "x\" tabindex=0 autofocus onfocus=window.__pwned=1 y=\"",
 "url": "http://testserver/admin/doc/details/x\" tabindex=0 autofocus onfocus=window.__pwned=1 y=\""}

which is rendered:

DOM attrs: class="sa-row", data-url="http://testserver/admin/doc/details/x",
           tabindex="0", autofocus="", onfocus="window.__pwned=1", y=""

window.__pwned is 1 with zero user interaction — autofocus + tabindex makes the injected row focusable and fires onfocus on render. An onmouseover variant fires as soon as the admin's cursor crosses the results list.

    .replace(/"/g, """)
    .replace(/'/g, "'");

Add these

[mmzeynalli]

Returns 500 for any model that has relationship and uses that in str.

smth like this

class Player(Base):
    team = relationship("Team")
    def __str__(self):
        return f"{self.name} ({self.team.name if self.team else '-'})"

[mmzeynalli]

Smth:

def palette_base_query(view: ModelView) -> Select:
    stmt = select(view.model)
    for relation in view._list_relations:
        stmt = stmt.options(selectinload(relation))
    return stmt

[mmzeynalli]

I think it does. If I check user session in request, then that should apply to global as well

[mmzeynalli]

This is not correct, your views does not have palette_search_query function

[mmzeynalli]

This func fires a new $.ajax on every debounce tick and never cancels the previous one, and saPaletteRender reads the term back out of the input box at render time (line 158) rather than using the term the response was for. Responses are not guaranteed to arrive in order, and the shorter term is usually the slower query because it matches more rows — so the common typing pattern loses the race.

[mmzeynalli]

Not used anywhere

[mmzeynalli]

Not tested. Reachable via a scoped search against a model with can_view_details = False or with no column_searchable_list

[mmzeynalli]

login_required answers an expired session with a 302 to the HTML login page. jQuery follows it, dataType: "json" fails to parse the login page, and the user sees "Search failed" with no hint that they need to log in again. Returning 401 for X-Requested-With: XMLHttpRequest (which palette.js:146 already sends) and having the error handler redirect would be a nicer dead end.

[mmzeynalli]

Validate values: max(0, value)

[mmzeynalli]

Move this a little down/up. You kinda split search related args (column_searchable_list, search_auto_submit)

[vahidzhe]

@mmzeynalli Thanks, especially for the XSS one. Fixed all ten, pushed as a new commit
(force-push would break the thread links).

37 tests now (was 30), passing on SQLite and a real PostgreSQL 16. ruff, mypy
and mkdocs build --strict all clean.

---

saPaletteEsc -> quotes not escaped. Confirmed your payload breaks out of
data-url before the fix. " and ' are now escaped too.

Relationship in __str__ crashes. Reproduced the DetachedInstanceError.
Fixed by eager-loading view._list_relations, same as list() and
get_model_objects() already do. Limitation: only covers relations listed in
column_list -> documented that convention explicitly since it wasn't written
down anywhere before.

list_query scoping should apply. Agreed. palette_base_query now builds
on view.list_query(request) instead of a bare select(model), so this and
the relationship fix share one change. Added a test with a tenant-filtered
list_query.

Docs example calls a method that doesn't exist. Correct -> it was a module
function, never actually invoked on self. palette_search_query is now a
real overridable method on ModelView, same pattern as palette_commands.

Debounce race condition. Fixed with a request sequence counter plus
xhr.abort() on the previous request; stale responses are dropped instead of
overwriting a newer result.

saPaletteSingular unused. Removed, along with saPaletteTerm (same
issue, found while fixing the race condition above).

Untested can_view_details=False / no-column_searchable_list path. Added
two tests covering both, reached via a scope.

302 redirect breaks the JSON client. Added palette_login_required, a
narrow guard used only by this endpoint, returning 401 JSON instead of an HTML
redirect. palette.js treats 401 as "go to login". Did not touch the shared
login_required -> it's correct for every other route.

Unvalidated negative config values. Clamped with max(0, value).

ClassVar placement. Moved palette_search / palette_search_limit next
to search_auto_submit, with the other search-related attributes.

Ready for another pass.

[mmzeynalli]

The one I'd call blocking is the javascript: sink in palette.js — it's one line to guard. The asyncio.gather failure isolation and the | tojson escaper are correctness; the "one query" badge, the silent model cap, and the layout change are accuracy and scope.

On the layout change specifically: it affects every deployment, not just palette users, so it needs calling out in the description even if it stays in this PR.

[mmzeynalli]

data-url is escaped correctly as an attribute, but this executes javascript: URLs. A command with url: "javascript:alert('sink')" fires on click.

Nothing server-side can produce that today, since every URL comes from request.url_for. But palette_commands is documented as returning an arbitrary url and the docstring example builds one, so a command URL derived from a DB field would be stored XSS. Can we guard at the sink?

if (url && /^(\/|https?:)/i.test(url)) { window.location.href = url; }

[mmzeynalli]

The eager-loading is right — the DetachedInstanceError reasoning in the docstring is correct. But it means "exactly one query" isn't accurate, and the UI shows a badge that literally says "one query" (oneQuery in palette.html).

Counted with an engine listener, scoped search on a model with one relationship in column_list:

SQL statements issued -> 2
  SELECT doc.id, doc.title, doc.tag_id FROM doc WHERE lower(...) LIKE ...
  SELECT tag.id, tag.name FROM tag WHERE tag.id IN (?, ?, ?, ?, ?)

With three relations, it's four. Could the badge go, or become 1 + len(view._list_relations)?

[mmzeynalli]

Without return_exceptions=True, one bad model breaks the whole palette. I gave one model a palette_search_query that raises:

unscoped, one model raises -> 500
scoped into healthy model  -> 200, 1 records

palette_search_query is a documented override, and a transient error on one table would do the same. Could we degrade instead — return_exceptions=True, log it, skip that model's chunk? The user loses one model's hits rather than the search box.

[mmzeynalli]

The cap slices in registration order, so which models get searched is incidental. With 15 searchable models registered I get hits from 7 and no indication about the rest — a term that only matches the twelfth model reads as "Nothing found".

The cap is right; the silence is the problem. Could the response carry searched/total counts so the UI can say "searched 8 of 15 models, keep typing to narrow"?

[mmzeynalli]

This still persists

[mmzeynalli]

This hunk does two things beyond adding the trigger: it moves Logout out of the sidebar into the topbar, and makes the topbar render unconditionally where it was gated on show_switcher. Rendered against both trees with an auth backend and no i18n config:

main : logout inside sidebar: True   <header> topbar exists: False
head : logout inside sidebar: False  <header> topbar exists: True

So every deployment gets a new topbar and a relocated Logout, whether or not they use the palette. Reasonable — the trigger needs a home — but it will break anyone who overrode layout.html, so it deserves a line in the PR description and the changelog.