TangleLatex API#

def __init__(
    self,
    latex: str,
    parameters: Mapping[str, Mapping[str, Any]],
    notes: Mapping[str, Any] | None = None,
    *,
    display_mode: bool = True,
    editor: str = "popover",
    reveal_all_on_drag: bool = False,
    theme: str = "auto",
    **kwargs: Any,
) -> None:
    """Create a TangleLatex widget.

    Args:
        latex: KaTeX source containing one or more ``\\tangle{name}`` markers.
        parameters: Mapping from marker name to its numeric configuration.
            ``value`` is required. Optional keys are ``min_value``,
            ``max_value``, ``step``, ``digits``, ``display`` (``"number"``
            or ``"symbol"``), ``symbol``, ``label``, ``pixels_per_step``,
            and ``color`` (a CSS string or ``{"light": ..., "dark": ...}``).
        notes: Plain-language explanations drawn next to the formula with
            an arrow to the part they explain. Wrap the part in
            ``\\note{name}{tex}`` (any part, including one occurrence of a
            ``\\tangle{...}``) and map ``name`` to its text, or to a dict
            with ``text``, ``side`` (``"auto"``, ``"top"``, ``"bottom"``)
            and ``color``. A note wrapping exactly one parameter takes
            its color and lights up while that parameter is dragged. Note
            text is plain text with inline ``$...$`` math and ``**bold**``.
        display_mode: Render using KaTeX display mode.
        editor: Numeric click editor style: ``"popover"`` or ``"inline"``.
        reveal_all_on_drag: Reveal every symbolic parameter as a number while
            any parameter is actively dragged. When false, reveal only the
            selected parameter.
        theme: Color theme: ``"auto"``, ``"light"``, or ``"dark"``.
        **kwargs: Forwarded to ``anywidget.AnyWidget``.
    """
    if not isinstance(latex, str):
        raise ValueError("latex must be a string.")
    if editor not in {"popover", "inline"}:
        raise ValueError("editor must be 'popover' or 'inline'.")
    if theme not in {"auto", "light", "dark"}:
        raise ValueError("theme must be 'auto', 'light', or 'dark'.")

    marker_names = set(_MARKER_RE.findall(latex))
    if not marker_names:
        raise ValueError("latex must contain at least one \\tangle{name} marker.")
    normalized = _normalize_parameters(parameters)
    configured_names = set(normalized)
    missing = sorted(marker_names - configured_names)
    unused = sorted(configured_names - marker_names)
    if missing:
        raise ValueError(
            "missing configuration for parameter marker(s): " + ", ".join(missing)
        )
    if unused:
        raise ValueError(
            "parameter configuration not referenced by latex: " + ", ".join(unused)
        )

    normalized_notes = _normalize_notes(notes or {}, latex=latex, parameters=normalized)
    note_markers = set(_NOTE_MARKER_RE.findall(latex))
    missing_notes = sorted(note_markers - set(normalized_notes))
    unused_notes = sorted(set(normalized_notes) - note_markers)
    if missing_notes:
        raise ValueError("missing note for marker(s): " + ", ".join(missing_notes))
    if unused_notes:
        raise ValueError(
            "note(s) not referenced by latex: " + ", ".join(unused_notes)
        )

    values = {name: spec["value"] for name, spec in normalized.items()}
    super().__init__(
        latex=latex,
        parameters=normalized,
        notes=normalized_notes,
        values=values,
        committed_values=dict(values),
        display_mode=display_mode,
        editor=editor,
        reveal_all_on_drag=reveal_all_on_drag,
        theme=theme,
        **kwargs,
    )