Serve¶

def build_run_picker(self) -> None:
    """The indexed-run select and the bundle-path field, both driving the same run variable; built into the app bar, its one place."""
    with labelled("Run"):
        picker(str(FieldVar.RUN), str(FieldVar.RUN_ITEMS), placeholder="No Run Selected", width=RUN_WIDTH)

    Input(
        model=str(FieldVar.RUN_TEXT),
        placeholder="Bundle Path",
        classes=PATH_WIDTH,
        aria_label="Bundle path",
        on_key_down=self.opening(),
    )
    with Button(size="icon-sm", variant="ghost", title="Open the bundle at that path", on_click=self.callback(self.controller.open_text)):
        Icon("folder")

def opening(self) -> react.Callback:
    """The bundle-path field's Enter: the text is committed and opened in one client-side step."""
    text = f"{EVENT}.target.value"

    return react.Callback(f'{EVENT}.key === "{ENTER}" && (trame.state.set("{FieldVar.RUN_TEXT}", {text}), trame.state.set("{FieldVar.RUN}", {text}))')

def build_colormap(self) -> None:
    """The field colormap picker: searchable, filtered by type and favorites, the arrow keys stepping through it while it is closed."""
    Combobox(
        model=str(FieldVar.COLORMAP),
        items=react.Bind(str(FieldVar.COLORMAP_ITEMS)),
        filters=COLORMAP_FILTERS,
        search_placeholder="Search Colormaps",
        aria_label="Colormap",
    )

def build_body_colormap(self) -> None:
    """The body colormap picker as a swatch in the color column, reading Same as field while no body takes it."""
    Combobox(
        value=react.Bind(str(FieldVar.BODY_COLORMAP_SHOWN)),
        on_value_change=self.callback(self.controller.on_body_colormap_pick, args=f"[{EVENT}]"),
        items=react.Bind(str(FieldVar.COLORMAP_ITEMS)),
        lead=react.Bind(str(FieldVar.BODY_LEAD)),
        filters=COLORMAP_FILTERS,
        compact=True,
        search_placeholder="Search Colormaps",
        aria_label="Body colormap",
    )

def slider(self, model: FieldVar, label: str, bounds: tuple[float, float | react.Bind], step: float) -> None:
    """A slider over `model` whose thumbs move with the drag and whose scene follows the release.

    Args:
        model: The state variable holding the thumb values.
        label: The slider's accessible name.
        bounds: The low and high ends; the high end may be a client expression.
        step: The step between values.
    """
    Slider(
        value=react.Bind(str(model)),
        on_value_change=setter(str(model)),
        on_value_commit=self.callback(self.controller.on_commit),
        min_=bounds[0],
        max_=bounds[1],
        step=step,
        aria_label=label,
    )

def build_range(self) -> None:
    """The Auto range switch over the two-thumb colour range across the data range, its ends read out above it."""
    setting(FieldVar.AUTO_CLIM, "Auto range")
    with html.Div(classes=STACK):
        readouts(react.Bind(f"{FieldVar.CLIM}[0].toPrecision({PRECISION})"), react.Bind(f"{FieldVar.CLIM}[1].toPrecision({PRECISION})"))
        Slider(
            value=react.Bind(str(FieldVar.CLIM)),
            on_value_change=setter(str(FieldVar.CLIM)),
            on_value_commit=self.callback(self.controller.on_commit),
            min_=react.Bind(str(FieldVar.CLIM_MIN)),
            max_=react.Bind(str(FieldVar.CLIM_MAX)),
            step=react.Bind(str(FieldVar.CLIM_STEP)),
            disabled=react.Bind(str(FieldVar.AUTO_CLIM)),
            aria_label="Color range",
        )

def build_opacity(self) -> None:
    """The Opacity mapping switch and, while it is on, the opacity at each end of the color range; the body table holds the overall opacity."""
    setting(FieldVar.OPACITY_MAPPING, "Opacity mapping")
    with react.If(str(FieldVar.OPACITY_MAPPING)), html.Div(classes=STACK):
        readouts(react.Bind(f"{FieldVar.OPACITY_RANGE}[0].toFixed(2)"), react.Bind(f"{FieldVar.OPACITY_RANGE}[1].toFixed(2)"))
        self.slider(FieldVar.OPACITY_RANGE, "Opacity", OPACITY_RANGE, OPACITY_STEP)

def build_field(self) -> None:
    """The field section: what is shown and how it is colored, from the field select to the opacity mapping."""
    with captioned("Quantity"):
        picker(str(FieldVar.FIELD), str(FieldVar.FIELDS), placeholder=NO_RUN, width=FULL_WIDTH)

    with captioned("Mode"):
        picker(str(FieldVar.MODE), str(FieldVar.MODES), placeholder=NO_RUN, width=FULL_WIDTH)

    with captioned("Colormap"):
        self.build_colormap()

    with html.Div(classes=STACK):
        setting(FieldVar.INVERT, "Invert colormap")
        setting(FieldVar.LOG_SCALE, "Log scale")
        setting(FieldVar.OUTLINE, "Outline")

    self.build_range()
    self.build_opacity()

def build_bodies(self) -> None:
    """The body table: the All bodies row with the body colormap, then a row per body and per material group, every row checkbox, name, color and opacity."""
    controller = self.controller
    visible = str(FieldVar.VISIBLE_BODIES)
    row = ITEM
    members = f"{row}.{RowKey.MEMBERS}"

    def opacity_slider(value: str, change: react.Callback, commit: react.Callback, label: str | react.Bind) -> None:
        Slider(
            value=react.Bind(value),
            on_value_change=change,
            on_value_commit=commit,
            min_=OPACITY_RANGE[0],
            max_=OPACITY_RANGE[1],
            step=OPACITY_STEP,
            aria_label=label,
        )

    with html.Div(classes=BODY_TABLE):
        with html.Div(classes=BODY_ROW):
            Checkbox(
                checked=react.Bind(f"{visible}.length === 0 ? false : {visible}.length === {FieldVar.BODY_ROWS}.filter(r => !r.{RowKey.GROUP}).length || 'indeterminate'"),
                on_checked_change=react.Callback(f"trame.state.set({json.dumps(visible)}, {EVENT} === true ? {FieldVar.BODY_ROWS}.filter(r => !r.{RowKey.GROUP}).map(r => r.{RowKey.ID}) : [])"),
                aria_label="Show every body",
            )
            html.Span(ALL_BODIES, classes=GROUP_NAME)
            self.build_body_colormap()
            opacity_slider(str(FieldVar.OPACITY), setter(str(FieldVar.OPACITY)), self.callback(controller.on_commit), "Opacity of every body")

        with react.For(items=str(FieldVar.BODY_ROWS), name=row), html.Div(classes=BODY_ROW):
            Checkbox(
                checked=react.Bind(f"{members}.every(m => {visible}.includes(m)) || ({members}.some(m => {visible}.includes(m)) && 'indeterminate')"),
                on_checked_change=self.callback(controller.on_row_visible, args=f"[{row}.{RowKey.ID}, {EVENT}]"),
                aria_label=react.Bind(f"'Show ' + {row}.{RowKey.TITLE}"),
            )
            html.Span(
                [react.Bind(f"{row}.{RowKey.TITLE}")],
                classes=react.Bind(f"{row}.{RowKey.GROUP} ? {json.dumps(GROUP_NAME)} : {row}.{RowKey.MEMBER} ? {json.dumps(MEMBER_NAME)} : {json.dumps(BODY_NAME)}"),
                title=react.Bind(f"{row}.{RowKey.TITLE}"),
            )
            with html.Span(classes=CHIP_SLOT):
                painted = f"{row}.{RowKey.PAINT} !== {json.dumps(str(BodyPaint.FIELD))}"
                with react.If(painted):
                    ColorInput(
                        value=react.Bind(f"{row}.{RowKey.COLOR}"),
                        on_change=self.callback(controller.on_row_color, args=f"[{row}.{RowKey.ID}, {EVENT}.target.value]"),
                        classes=COLOR_CHIP,
                        title=react.Bind(f"{row}.{RowKey.PAINT} === {json.dumps(str(BodyPaint.COLORMAP))} ? 'From the body colormap: pick to fix a color' : 'A fixed color'"),
                        aria_label=react.Bind(f"{row}.{RowKey.TITLE} + ' color'"),
                    )
                    with Button(
                        size="icon-xs",
                        variant="ghost",
                        classes=CHIP_CLEAR,
                        title="Back to the field colormap",
                        aria_label=react.Bind(f"{row}.{RowKey.TITLE} + ' back to the field colormap'"),
                        on_click=self.callback(controller.on_row_field, args=f"[{row}.{RowKey.ID}]"),
                    ):
                        Icon("x")

                with react.If(f"!({painted})"):
                    Button(
                        size="icon-xs",
                        variant="ghost",
                        classes=CHIP,
                        style={"background": react.Bind(str(FieldVar.FIELD_GRADIENT))},
                        title="Field colormap: click for the body colormap",
                        aria_label=react.Bind(f"{row}.{RowKey.TITLE} + ' to the body colormap'"),
                        on_click=self.callback(controller.on_row_colormap, args=f"[{row}.{RowKey.ID}]"),
                    )

            opacity_slider(
                f"{row}.{RowKey.OPACITY}",
                self.callback(controller.on_row_opacity, args=f"[{row}.{RowKey.ID}, {EVENT}[0]]"),
                self.callback(controller.on_commit),
                react.Bind(f"{row}.{RowKey.TITLE} + ' opacity'"),
            )

def build_lines(self) -> None:
    """The field-line section: the switch, the seeds, the region and the two integration sliders."""
    setting(FieldVar.STREAMLINES, "Show field lines", disabled=react.Bind(f"!{FieldVar.HAS_FLUX}"))

    with captioned("Seeds"):
        picker(str(FieldVar.SEED_PLACEMENT), str(FieldVar.SEED_PLACEMENTS), width=FULL_WIDTH)

    with captioned("Integrate within"):
        picker(str(FieldVar.LINES_BODY), str(FieldVar.LINES_BODIES), placeholder=WHOLE_DOMAIN_LABEL, width=FULL_WIDTH)

    with html.Div(classes=STACK):
        readouts("Seed count", react.Bind(seed_count()))
        self.slider(FieldVar.LINE_COUNT, "Seeds per axis", (LINE_COUNT_MIN, react.Bind(str(FieldVar.LINE_COUNT_MAX))), 1)

    with html.Div(classes=STACK):
        readouts("Length", react.Bind(f"{FieldVar.MAX_LENGTH}[0].toPrecision(2)"))
        self.slider(FieldVar.MAX_LENGTH, "Line length", MAX_LENGTH_RANGE, MAX_LENGTH_STEP)

def build(self) -> None:
    """Builds the busy bar over the field, field-line and body sections."""

    def section(value: str, heading: str, body: Callable[[], None]) -> None:
        with AccordionItem(value=value, classes=str(Cls.SECTION_ITEM)):
            AccordionTrigger(heading, classes=str(Cls.SECTION_TRIGGER))
            with AccordionContent(classes=str(Cls.SECTION_BODY)):
                body()

    with html.Div(classes=str(Cls.CONTROLS)):
        with react.If(str(FieldVar.BUSY)):
            Progress(value=BUSY_FULL, classes=str(Cls.BUSY))

        with Accordion(type_="multiple", default_value=OPEN_SECTIONS, classes=str(Cls.SECTIONS)):
            section(FIELD_SECTION, "Field", self.build_field)
            section(LINES_SECTION, "Field Lines", self.build_lines)
            section(BODIES_SECTION, "Bodies", self.build_bodies)

def dispose(self) -> None:
    """Detaches from the controller, then releases the panel."""
    self.controller.detach(self)
    super().dispose()

def show(self, figure: go.Figure, bodies: Sequence[str]) -> None:
    """Replaces the figure, remembering which body each mesh trace is."""
    self.bodies = list(bodies)
    self.update(figure)

def clear(self) -> None:
    """Empties the figure."""
    self.bodies = []
    self.update(go.Figure())

def on_visible(self, visible: bool) -> None:
    """Tells the controller whether the plot is on screen."""
    self.controller.on_visible(self.id, visible)

def dispose(self) -> None:
    """Detaches from the controller, then releases the panel."""
    self.controller.detach(self)
    super().dispose()

def on_restyle(self, payload: object) -> None:
    """Mirrors a legend toggle into the visible-bodies state, so the tree and the 3D view follow."""
    parts = cast("list[object]", payload) if isinstance(payload, list) else []
    if len(parts) != 2 or not isinstance(parts[0], Mapping) or not isinstance(parts[1], list):
        return

    flags = cast("Mapping[str, object]", parts[0]).get("visible")
    indices = cast("list[object]", parts[1])
    if not isinstance(flags, list):
        return

    shown = set(names_of(self.state[FieldVar.VISIBLE_BODIES]))
    for index, flag in zip(indices, cast("list[object]", flags), strict=False):
        if not isinstance(index, int) or not 0 <= index < len(self.bodies):
            continue

        name = self.bodies[index]
        if flag is True:
            shown.add(name)
        else:
            shown.discard(name)

    with self.state:
        self.state[FieldVar.VISIBLE_BODIES] = [name for name in self.bodies if name in shown]

def clear(self) -> None:
    """Empties the plotter and pushes the empty frame."""
    self.plotter.clear()
    self.renderable = None
    self.push()

def on_visible(self, visible: bool) -> None:
    """Tells the scene and the controller whether the view is on screen."""
    super().on_visible(visible)
    self.controller.on_visible(self.id, visible)

def dispose(self) -> None:
    """Detaches from the controller, then frees the view."""
    self.controller.detach(self)
    super().dispose()

def build(self) -> None:
    """Pushes the figure into the state and builds the plot bound to it."""
    # A rebuilt panel must push its figure: a bound default only fills a variable the last build left empty.
    self.state[self.key(FIGURE_KEY)] = self.encode(self.initial)
    self.plot = Plot(figure=react.Bind(self.key(FIGURE_KEY)))

def encode(self, figure: go.Figure) -> Json:
    """The figure as plain JSON with the modebar switch and the export name it carries."""
    document = cast("Json", json.loads(figure.to_json()))
    document["config"] = {"displayModeBar": self.mode_bar, "toImageButtonOptions": export_options(figure)}

    return document

def update(self, figure: go.Figure) -> None:
    """Replaces the figure."""
    with self.state:
        self.state[self.key(FIGURE_KEY)] = self.encode(figure)

def bind(self, event: PlotEvent, handler: EventHandler) -> None:
    """Routes a plotly event to `handler` with the event payload as its one argument."""
    if self.plot is None:
        return

    setattr(self.plot, f"{EVENT_PREFIX}{event}", self.callback(handler, args="[$event]"))
    self.refresh()

def build(self) -> None:
    """Adds the panel's widgets to its layout."""
    raise NotImplementedError

def key(self, name: str) -> str:
    """A state variable or trigger name namespaced to this panel."""
    return f"{self.id}_{name}".replace("-", "_")

def status(self, message: str) -> None:
    """Reports in the shell's status line."""
    self.app.status(message)

def refresh(self) -> None:
    """Pushes the template again after its widgets changed."""
    self.layout.flush_content()

def callback(self, fn: Handler, args: str | None = None) -> react.Callback:
    """A client event handler calling `fn` with the JS `args`, unregistered again when the panel is disposed."""
    self.bound.append(fn)

    return react.Callback(fn, args=args)

def listen[L: Listener](self, *names: str) -> Callable[[L], L]:
    """Registers a state listener like `state.change`, one the panel drops again when disposed."""

    def register(listener: L) -> L:
        _ = self.state.change(*names)(listener)
        self.listeners.append(listener)

        return listener

    return register

def dispose(self) -> None:
    """Releases what the panel registered on the server once it left the dock: triggers, state listeners and controller slots."""
    self._unbind_annotated_methods()

    # trame offers no public removal of a listener, nor a list of the triggers it named for a widget's callbacks; its own unbind reaches into the same dicts.
    for registered in self.state._change_callbacks.values():
        registered[:] = [(fn, translator) for fn, translator in registered if fn not in self.listeners]

    owned = [fn for fn in self.ctrl._triggers_fn2name if getattr(fn, "__self__", None) is self or fn in self.bound]
    for fn in owned:
        _ = self.ctrl.trigger_unregister(fn)

    self.listeners.clear()
    self.bound.clear()

def succeed(self, previous: "PanelComponent") -> None:
    """Called on a panel rebuilt under the id of `previous`, already disposed, to carry over what a fresh build would lose."""

def on_visible(self, visible: bool) -> None:
    """Called when dockview shows or hides the panel."""

def on_layout_changed(self) -> None:
    """Called after the dock re-laid out its groups."""

def query(self) -> RunQuery:
    """The run index query before the toolbar's filters."""
    return RunQuery(self.telemetry.runs.scan())

def index(self) -> pl.DataFrame:
    """The narrowed index frame, with the live claims joined on."""
    return self.narrowing.apply(self.query()).frame()

def table_frame(self, frame: pl.DataFrame) -> pl.DataFrame:
    """One index frame as the table's rows, remembering which of its runs are claimed and where their bundles live."""
    self.live = live_ids(frame)
    self.directories = set(cast("list[str]", frame[RunColumn.RUNS_DIR].unique().to_list()))

    return pl.DataFrame(run_rows(frame, self.live), schema=RUN_SCHEMA)