"""Stash-style filter bars, built from FilterSelect widgets."""
from typing import NamedTuple
from common.components.core import BaseComponent, Element, Node, Safe
from common.components.custom_elements import _FilterBarElement
from common.components.date_range_picker import DateRangePicker
from common.components.primitives import Checkbox, Div, Input, Label, Radio, Span
from common.components.search_select import (
DEFAULT_PREFETCH,
FilterSelect,
LabeledOption,
)
class FilterChoice(NamedTuple):
"""Parsed include/exclude/modifier state of a filter field from filter JSON.
``selected`` and ``excluded`` are lists of ``(value, label)`` pairs. For
model-backed fields the label is embedded in the filter JSON (Stash-style);
for enum fields the label is resolved from the fixed option list.
"""
selected: list[LabeledOption]
excluded: list[LabeledOption]
modifier: str
class RangeValues(NamedTuple):
"""A (min, max) string pair parsed from a range filter criterion."""
min: str
max: str
class NumberValues(NamedTuple):
"""(value, value2, modifier) parsed from a numeric filter criterion."""
value: str
value2: str
modifier: str
_FILTER_LABEL_CLASS = "text-xs font-medium text-body uppercase tracking-wide"
_FILTER_CHECKBOX_CLASS = (
"rounded border-default-medium bg-neutral-secondary-medium "
"text-brand focus:ring-brand"
)
_FILTER_RADIO_CLASS = (
"rounded-full border-default-medium bg-neutral-secondary-medium "
"text-brand focus:ring-brand"
)
_FILTER_GRID_CLASS = "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4 gap-4 mb-4"
def _filter_parse(filter_json: str) -> dict:
if not filter_json:
return {}
try:
import json
loaded = json.loads(filter_json)
return loaded if isinstance(loaded, dict) else {}
except (ValueError, TypeError):
return {}
def _extract_labeled(items: list) -> list[LabeledOption]:
"""Convert filter values to ``(value, label)`` pairs.
UI-built filters carry ``{id, label}`` dicts; programmatically-built ones
(e.g. stats_links) carry bare ids/choices. A bare value uses itself as its
own label so the bar renders any valid filter instead of crashing."""
pairs: list[LabeledOption] = []
for item in items:
if isinstance(item, dict):
pairs.append((str(item["id"]), str(item["label"])))
else:
pairs.append((str(item), str(item)))
return pairs
def _filter_get_choice(existing: dict, field: str) -> FilterChoice:
raw = existing.get(field, {})
if not isinstance(raw, dict):
return FilterChoice([], [], "")
return FilterChoice(
selected=_extract_labeled(raw.get("value") or []),
excluded=_extract_labeled(raw.get("excludes") or []),
modifier=raw.get("modifier") or "",
)
def _parse_range(existing: dict, key: str) -> RangeValues:
"""Extract (min, max) from a range filter criterion, defaulting to ("", "")."""
field = existing.get(key, {})
if not isinstance(field, dict):
return RangeValues("", "")
return RangeValues(str(field.get("value", "")), str(field.get("value2", "")))
def _parse_number(existing: dict, key: str) -> NumberValues:
"""Extract (value, value2, modifier) from a numeric filter criterion.
Backward compatible with old RangeSlider JSON: a stored GREATER_THAN /
LESS_THAN / BETWEEN criterion maps straight onto value/value2/modifier.
"""
field = existing.get(key, {})
if not isinstance(field, dict):
return NumberValues("", "", "EQUALS")
return NumberValues(
str(field.get("value", "")),
str(field.get("value2", "")),
str(field.get("modifier") or "EQUALS"),
)
def _parse_bool(existing: dict, key: str) -> bool:
"""Extract a boolean value from a filter criterion."""
field = existing.get(key, {})
if not isinstance(field, dict):
return False
return bool(field.get("value", False))
def _parse_bool_nullable(existing: dict, key: str) -> bool | None:
"""Extract a nullable boolean value from a filter criterion."""
if key not in existing:
return None
field = existing[key]
if not isinstance(field, dict):
return None
val = field.get("value")
if val is None:
return None
if isinstance(val, str):
if val.lower() in ("true", "1", "yes"):
return True
if val.lower() in ("false", "0", "no"):
return False
return bool(val)
# ── FilterSelect adapters ────────────────────────────────────────────────────
# Each list filter is a FilterSelect. Enum fields pre-render their small, fixed
# option set; model-backed fields fetch from a search endpoint on demand, with
# labels embedded in the filter JSON so pills render without a DB round-trip.
# Presence modifiers drive the pinned (Any)/(None) pseudo-options. They are
# mutually exclusive with value pills (selecting one clears the value set).
# Must match JS PRESENCE_MODIFIERS in search_select.js.
_PRESENCE_MODIFIERS = frozenset({"NOT_NULL", "IS_NULL"})
# M2M-only modifiers surfaced as additional pseudo-options in the dropdown.
# "any" (INCLUDES) is the implicit default when neither a presence nor an
# M2M modifier is set — no dedicated row needed. "none" (EXCLUDES) is
# redundant with individual exclude (✗) pills. Only INCLUDES_ALL and
# INCLUDES_ONLY can't be expressed through pills alone, so they are the
# only M2M modifiers with explicit UI.
_M2M_MODIFIERS: list[LabeledOption] = [
("INCLUDES_ALL", "(All)"),
("INCLUDES_ONLY", "(Only)"),
]
def _modifier_options(
nullable: bool, m2m_modifiers: list[LabeledOption] | None = None
) -> list[LabeledOption]:
"""Pinned pseudo-options rendered at the top of the dropdown.
Always includes ``(Any)`` (NOT_NULL); adds ``(None)`` (IS_NULL) when
``nullable`` is True. When ``m2m_modifiers`` is given (M2M fields only),
appends those rows (e.g. ``(All)`` / ``(Only)``)."""
options: list[LabeledOption] = [("NOT_NULL", "(Any)")]
if nullable:
options.append(("IS_NULL", "(None)"))
if m2m_modifiers:
options.extend(m2m_modifiers)
return options
def _split_modifier(modifier: str, has_m2m: bool = False) -> str:
"""Return the modifier value to surface as the modifier pill.
Presence modifiers (NOT_NULL / IS_NULL) are always surfaced. Non-presence
modifiers (INCLUDES / INCLUDES_ALL / INCLUDES_ONLY) only need a pill on M2M
fields — otherwise the modifier is just the implicit default.
"""
if modifier in _PRESENCE_MODIFIERS or not has_m2m:
return modifier
if modifier:
return modifier
return ""
def _enum_filter(field_name: str, options, choice: FilterChoice, *, nullable) -> Node:
"""A FilterSelect over a small, fully pre-rendered option set (enum field).
Enum fields are single-valued, so no M2M modifiers (all/only are
meaningless); only the presence modifier is surfaced.
"""
options_str = [(str(value), label) for value, label in options]
included = [
(value, _find_label(options_str, value)) for value, _label in choice.selected
]
excluded = [
(value, _find_label(options_str, value)) for value, _label in choice.excluded
]
modifier = _split_modifier(choice.modifier)
return FilterSelect(
field_name=field_name,
options=options_str,
included=included,
excluded=excluded,
modifier=modifier,
modifier_options=_modifier_options(nullable),
)
def _model_filter(
field_name: str,
choice: FilterChoice,
*,
search_url,
nullable,
m2m_modifiers: list[LabeledOption] | None = None,
) -> Node:
"""A FilterSelect backed by a search endpoint.
Labels are embedded in the filter JSON (Stash-style), so pills render
directly from ``choice`` with no DB round-trip. Pass ``m2m_modifiers`` for
many-to-many fields to surface ``(All)`` / ``(Only)`` pseudo-options in the
dropdown alongside the presence options.
"""
modifier = _split_modifier(choice.modifier, has_m2m=bool(m2m_modifiers))
return FilterSelect(
field_name=field_name,
included=[(value, label or value) for value, label in choice.selected],
excluded=[(value, label or value) for value, label in choice.excluded],
modifier=modifier,
modifier_options=_modifier_options(nullable, m2m_modifiers),
search_url=search_url,
prefetch=DEFAULT_PREFETCH,
)
def _filter_mins_to_hrs(val) -> str:
if val is None or val == "" or val == 0:
return ""
try:
mins = int(val)
except (TypeError, ValueError):
return ""
if mins == 0:
return ""
hrs = mins / 60
return str(int(hrs)) if hrs == int(hrs) else f"{hrs:.1f}"
def _widget_id(widget) -> str:
"""Best-effort id of a widget node, for the field label's ``for`` target.
Widgets are nodes carrying ``.attributes``, so the id is now reachable
directly (the old free ``Component`` string couldn't expose it).
"""
for name, value in getattr(widget, "attributes", []):
if name == "id":
return str(value)
return ""
def _filter_field(label: str, widget) -> Node:
"""A labelled filter field: ``… {widget}
``.
The label's ``for`` points at the widget's own id when it has one;
composite widgets without a single root id simply omit ``for``.
"""
label_attributes = [("class", _FILTER_LABEL_CLASS)]
widget_id = _widget_id(widget)
if widget_id:
label_attributes.append(("for", widget_id))
return Div(
attributes=[("class", "flex flex-col gap-1")],
children=[
Label(attributes=label_attributes, children=[label]),
widget,
],
)
def _filter_checkbox(name: str, label: str, checked: bool) -> Node:
"""Thin adapter mapping legacy checkbox filters to the generalized Checkbox primitive."""
return Checkbox(name=name, label=label, checked=checked)
def _filter_boolean_radio(name: str, label: str, value: bool | None) -> Node:
"""Renders a filter-specific boolean radio button group with 'True' and 'False' options."""
return Div(
attributes=[("class", "flex flex-col gap-1")],
children=[
Span(
attributes=[("class", _FILTER_LABEL_CLASS)],
children=[label],
),
Div(
attributes=[("class", "flex items-center gap-4 h-9")],
children=[
Radio(name=name, label="True", checked=value is True, value="true"),
Radio(
name=name, label="False", checked=value is False, value="false"
),
],
),
],
)
_DATE_RANGE_INPUT_CLASS = (
"w-full rounded-base border border-default-medium bg-neutral-secondary-medium "
"text-sm text-heading p-1.5 focus:ring-brand focus:border-brand"
)
def DateRangeFilter(
*,
label: str,
input_name_prefix: str,
min_value: str = "",
max_value: str = "",
min_placeholder: str = "From",
max_placeholder: str = "To",
) -> Node:
"""A pair of ``