diffract-core 0.2.1__py3-none-any.whl

diffract/viz/styling/palettes/color.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+
+class ColorPalette(Protocol):
+    """Protocol for mapping categorical values to colors."""
+
+    @property
+    def colors(self) -> list[str]:
+        """List of colors in the palette."""
+        ...
+
+    def get_color(self, value: Any, all_values: list[Any]) -> str:
+        """Get color for a specific value given all values."""
+        ...
+
+
+@dataclass(slots=True)
+class DefaultColorPalette:
+    """Default discrete color palette."""
+
+    _colors: list[str] = field(
+        default_factory=lambda: [
+            "navy",
+            "crimson",
+            "green",
+            "chocolate",
+            "orange",
+            "violet",
+            "purple",
+            "blue",
+            "grey",
+            "teal",
+        ]
+    )
+
+    @property
+    def colors(self) -> list[str]:
+        """List of colors in the palette."""
+        return self._colors
+
+    def get_color(self, value: Any, all_values: list[Any]) -> str:
+        """Return the color assigned to a value given all values."""
+        try:
+            idx = list(all_values).index(value)
+        except ValueError:
+            idx = 0
+        return self._colors[idx % len(self._colors)]
+
+
+@dataclass(slots=True)
+class DarkColorPalette:
+    """Color palette optimized for dark themes."""
+
+    _colors: list[str] = field(
+        default_factory=lambda: [
+            "#5dade2",
+            "#f1948a",
+            "#58d68d",
+            "#f7dc6f",
+            "#bb8fce",
+            "#85c1e9",
+            "#f8c471",
+            "#abebc6",
+            "#d7bde2",
+            "#aed6f1",
+        ]
+    )
+
+    @property
+    def colors(self) -> list[str]:
+        """List of colors in the palette."""
+        return self._colors
+
+    def get_color(self, value: Any, all_values: list[Any]) -> str:
+        """Return the color assigned to a value given all values."""
+        try:
+            idx = list(all_values).index(value)
+        except ValueError:
+            idx = 0
+        return self._colors[idx % len(self._colors)]

diffract/viz/styling/palettes/dashes.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+LINE_DASHES = ["solid", "dot", "dash", "longdash", "dashdot", "longdashdot"]
+
+
+class DashPalette(Protocol):
+    """Protocol for line dash pattern palettes."""
+
+    @property
+    def dashes(self) -> list[str]:
+        """List of dash patterns in the palette."""
+        ...
+
+
+@dataclass(slots=True)
+class DefaultDashPalette:
+    """Default line dash palette."""
+
+    _dashes: list[str] = field(default_factory=lambda: LINE_DASHES.copy())
+
+    @property
+    def dashes(self) -> list[str]:
+        """List of dash patterns in the palette."""
+        return self._dashes

diffract/viz/styling/palettes/symbols.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+MARKER_SYMBOLS = [
+    "circle",
+    "square",
+    "diamond",
+    "cross",
+    "x",
+    "triangle-up",
+    "triangle-down",
+    "triangle-left",
+    "triangle-right",
+    "pentagon",
+    "hexagon",
+    "star",
+    "hourglass",
+    "bowtie",
+]
+
+
+class SymbolPalette(Protocol):
+    """Protocol for marker symbol palettes."""
+
+    @property
+    def symbols(self) -> list[str]:
+        """List of symbols in the palette."""
+        ...
+
+
+@dataclass(slots=True)
+class DefaultSymbolPalette:
+    """Default marker symbol palette."""
+
+    _symbols: list[str] = field(default_factory=lambda: MARKER_SYMBOLS.copy())
+
+    @property
+    def symbols(self) -> list[str]:
+        """List of symbols in the palette."""
+        return self._symbols

diffract/viz/styling/resolvers/__init__.py

@@ -0,0 +1,11 @@
+from .categorical import CategoricalPropertyResolver
+from .color import ColorResolver, ColorSource, ResolvedColor
+from .numeric import NumericPropertyResolver
+
+__all__ = [
+    "CategoricalPropertyResolver",
+    "ColorResolver",
+    "ColorSource",
+    "NumericPropertyResolver",
+    "ResolvedColor",
+]

diffract/viz/styling/resolvers/categorical.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from diffract.viz.data import DataType, Entry, FieldRef
+from diffract.viz.data.extraction import get_field_data
+
+
+@dataclass
+class CategoricalPropertyResolver:
+    """Resolves categorical FieldRef values with optional mapping to candidates."""
+
+    candidates: list[str] | None = None
+
+    def resolve(
+        self,
+        source: FieldRef | str | None,
+        entries: dict[str, Entry] | None = None,
+    ) -> str | list[str] | None:
+        """Resolve a categorical source into a value or list of values.
+
+        Args:
+            source: A literal string, a FieldRef, or None.
+            entries: Entries used to resolve a FieldRef, if given.
+
+        Returns:
+            The literal string, the resolved per-entry values, or None.
+        """
+        match source:
+            case None:
+                return None
+            case str():
+                return source
+            case FieldRef():
+                return self._resolve_field_ref(source, entries)
+
+    def _resolve_field_ref(
+        self,
+        ref: FieldRef,
+        entries: dict[str, Entry] | None,
+    ) -> list[str] | None:
+        if entries is None:
+            return None
+
+        values, data_type, _ = get_field_data(entries, ref.field)
+        if ref.data_type is not None:
+            data_type = ref.data_type
+
+        if data_type != DataType.CATEGORICAL:
+            raise ValueError(
+                f"Field '{ref.field}' must be categorical for this property, "
+                f"got {data_type.name}"
+            )
+
+        str_values = [str(v) for v in values]
+
+        if self.candidates is None:
+            return str_values
+
+        unique = list(dict.fromkeys(str_values))
+        order_indices = ref.ordering.argsort(unique)
+        sorted_unique = [unique[i] for i in order_indices]
+        mapping = {
+            v: self.candidates[i % len(self.candidates)]
+            for i, v in enumerate(sorted_unique)
+        }
+
+        return [mapping[v] for v in str_values]

diffract/viz/styling/resolvers/color.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from diffract.viz.data import DataType, Entry, FieldRef
+from diffract.viz.data.extraction import get_field_data
+from diffract.viz.styling.palettes import ColorPalette, DefaultColorPalette
+from diffract.viz.styling.sources import ColorSource
+
+__all__ = ["ColorResolver", "ColorSource", "ResolvedColor"]
+
+
+@dataclass
+class ResolvedColor:
+    """Resolved color result: concrete colors and/or numeric values."""
+
+    color: str | list[str] | None = None
+    values: list[float] | None = None
+
+
+@dataclass
+class ColorResolver:
+    """Resolves color sources into concrete colors or coloraxis config."""
+
+    palette: ColorPalette = field(default_factory=DefaultColorPalette)
+
+    def resolve(
+        self,
+        source: ColorSource,
+        entries: dict[str, Entry] | None = None,
+    ) -> ResolvedColor:
+        """Resolve a color source into concrete colors."""
+        match source:
+            case None:
+                return ResolvedColor()
+            case str():
+                return ResolvedColor(color=source)
+            case FieldRef():
+                return self._resolve_field_ref(source, entries)
+
+    def _resolve_field_ref(
+        self,
+        ref: FieldRef,
+        entries: dict[str, Entry] | None,
+    ) -> ResolvedColor:
+        if entries is None:
+            return ResolvedColor()
+
+        values, data_type, _ = get_field_data(entries, ref.field)
+        if ref.data_type is not None:
+            data_type = ref.data_type
+
+        match data_type:
+            case DataType.CATEGORICAL:
+                return self._resolve_categorical(values, ref)
+            case DataType.NUMERIC:
+                return self._resolve_numeric(values)
+
+    def _resolve_categorical(self, values: list[Any], ref: FieldRef) -> ResolvedColor:
+        unique_values = list(dict.fromkeys(values))
+        order_indices = ref.ordering.argsort(unique_values)
+        sorted_unique = [unique_values[i] for i in order_indices]
+        colors = [self.palette.get_color(v, sorted_unique) for v in values]
+        return ResolvedColor(color=colors)
+
+    def _resolve_numeric(self, values: list[Any]) -> ResolvedColor:
+        float_values: list[Any] = []
+        for v in values:
+            if v is None:
+                float_values.append(float("nan"))
+            else:
+                try:
+                    float_values.append(float(v))
+                except (TypeError, ValueError):
+                    float_values.append(v)
+        return ResolvedColor(values=float_values)

diffract/viz/styling/resolvers/numeric.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import numpy as np
+
+from diffract.viz.data import DataShape, DataType, Entry, FieldRef
+from diffract.viz.data.extraction import get_field_data
+
+
+@dataclass
+class NumericPropertyResolver:
+    """Resolves numeric FieldRef values with optional normalization."""
+
+    output_range: tuple[float, float] | None = None
+
+    def resolve(
+        self,
+        source: FieldRef | float | None,
+        entries: dict[str, Entry] | None = None,
+    ) -> float | list[float] | None:
+        """Resolve a numeric source into a value or list of values.
+
+        Args:
+            source: A literal number, a FieldRef, or None.
+            entries: Entries used to resolve a FieldRef, if given.
+
+        Returns:
+            The literal number, the resolved per-entry values, or None.
+        """
+        match source:
+            case None:
+                return None
+            case int() | float():
+                return source
+            case FieldRef():
+                return self._resolve_field_ref(source, entries)
+
+    def _resolve_field_ref(
+        self,
+        ref: FieldRef,
+        entries: dict[str, Entry] | None,
+    ) -> list[float] | None:
+        if entries is None:
+            return None
+
+        values, data_type, data_shape = get_field_data(entries, ref.field)
+        if ref.data_type is not None:
+            data_type = ref.data_type
+
+        if data_type != DataType.NUMERIC:
+            raise ValueError(
+                f"Field '{ref.field}' must be numeric for this property, "
+                f"got {data_type.name}"
+            )
+
+        if data_shape == DataShape.SCALAR:
+            float_values = [float(v) if v is not None else float("nan") for v in values]
+        else:
+            float_values = [
+                v if v is not None else [float("nan")] * len(v) for v in values
+            ]
+
+        return self._normalize(float_values)
+
+    def _normalize(
+        self,
+        values: list[float | list[float]],
+        data_min: float | None = None,
+        data_max: float | None = None,
+    ) -> list[float | list[float]]:
+        if self.output_range is None:
+            return values
+
+        if isinstance(values[0], Iterable):
+            for v in values:
+                valid = [v_item for v_item in v if not math.isnan(v_item)]
+                partial_min, partial_max = min(valid), max(valid)
+                if data_min is None or partial_min < data_min:
+                    data_min = partial_min
+                if data_max is None or partial_max > data_max:
+                    data_max = partial_max
+            return [self._normalize(v, data_min, data_max) for v in values]
+        valid = [v for v in values if not math.isnan(v)]
+        if not valid:
+            return values
+
+        if data_min is None:
+            data_min = min(valid)
+
+        if data_max is None:
+            data_max = max(valid)
+
+        if data_min == data_max:
+            mid = (self.output_range[0] + self.output_range[1]) / 2
+            return [mid if not math.isnan(v) else float("nan") for v in values]
+
+        out_min, out_max = self.output_range
+        scale = (out_max - out_min) / (data_max - data_min)
+
+        return np.array(
+            [
+                out_min + (v - data_min) * scale if not math.isnan(v) else float("nan")
+                for v in values
+            ]
+        )

diffract/viz/styling/sources.py

@@ -0,0 +1,27 @@
+"""Typed sources for style properties that accept literals or field names.
+
+Each alias annotates ``FieldRef | str | None`` with the kind of plotly
+literal the property accepts. The renderer's config-time coercion pass
+uses the annotation to disambiguate bare strings deterministically: a
+string that is a valid literal of that kind stays a literal, anything
+else becomes a ``FieldRef``. Explicit ``FieldRef`` objects (e.g. the
+refs-style configs) bypass the rule entirely.
+"""
+
+from enum import Enum
+from typing import Annotated
+
+from diffract.viz.data import FieldRef
+
+
+class StyleLiteralKind(Enum):
+    """Kind of plotly literal a style property accepts besides a FieldRef."""
+
+    COLOR = "color"
+    SYMBOL = "symbol"
+    DASH = "dash"
+
+
+ColorSource = Annotated[FieldRef | str | None, StyleLiteralKind.COLOR]
+SymbolSource = Annotated[FieldRef | str | None, StyleLiteralKind.SYMBOL]
+DashSource = Annotated[FieldRef | str | None, StyleLiteralKind.DASH]

diffract/viz/styling/theme/__init__.py

@@ -0,0 +1,29 @@
+from .applier import apply_theme
+from .components import (
+    AxesStyle,
+    BackgroundStyle,
+    ColorbarStyle,
+    LayoutStyle,
+    LegendStyle,
+    TypographyStyle,
+)
+from .presets import DARK_THEME, DEFAULT_THEME, MINIMAL_THEME
+from .theme import Theme
+
+__all__ = [
+    "DARK_THEME",
+    # Presets
+    "DEFAULT_THEME",
+    "MINIMAL_THEME",
+    "AxesStyle",
+    "BackgroundStyle",
+    "ColorbarStyle",
+    # Components
+    "LayoutStyle",
+    "LegendStyle",
+    # Theme
+    "Theme",
+    "TypographyStyle",
+    # Applier
+    "apply_theme",
+]

diffract/viz/styling/theme/applier.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import plotly.graph_objects as go
+
+    from .theme import Theme
+
+
+def apply_theme(fig: go.Figure, theme: Theme) -> go.Figure:
+    """Apply figure-level styling from theme.
+
+    This applies layout, typography, background, legend, and colorbar styling.
+    Does NOT override trace-specific settings or axes configured by configurators.
+
+    Args:
+        fig: Plotly Figure to style.
+        theme: Theme to apply.
+
+    Returns:
+        The same figure (mutated in place) for chaining.
+    """
+    _apply_layout(fig, theme)
+    _apply_background(fig, theme)
+    _apply_typography(fig, theme)
+    _apply_legend(fig, theme)
+    _apply_colorbar_defaults(fig, theme)
+
+    return fig
+
+
+def _apply_layout(fig: go.Figure, theme: Theme) -> None:
+    """Apply layout dimensions and margins."""
+    if theme.layout.width is not None:
+        fig.update_layout(width=theme.layout.width)
+
+    if theme.layout.height is not None:
+        fig.update_layout(height=theme.layout.height)
+
+    fig.update_layout(margin=theme.layout.margin)
+
+
+def _apply_background(fig: go.Figure, theme: Theme) -> None:
+    """Apply background colors."""
+    fig.update_layout(
+        plot_bgcolor=theme.background.plot_bgcolor,
+        paper_bgcolor=theme.background.paper_bgcolor,
+    )
+
+
+def _apply_typography(fig: go.Figure, theme: Theme) -> None:
+    """Apply font settings."""
+    fig.update_layout(
+        font=dict(
+            family=theme.typography.font_family,
+            size=theme.typography.label_font_size,
+        ),
+        title=dict(
+            font=dict(
+                family=theme.typography.font_family,
+                size=theme.typography.title_font_size,
+            )
+        ),
+    )
+
+    # Style annotations with consistent font
+    fig.update_annotations(
+        font=dict(
+            family=theme.typography.font_family,
+            size=theme.typography.label_font_size,
+        )
+    )
+
+
+def _apply_legend(fig: go.Figure, theme: Theme) -> None:
+    """Apply legend styling."""
+    fig.update_layout(
+        legend=dict(
+            font=dict(
+                size=theme.legend.font_size,
+                family=theme.typography.font_family,
+            ),
+            bgcolor=theme.legend.bgcolor,
+            bordercolor=theme.legend.border_color,
+            borderwidth=theme.legend.border_width,
+        )
+    )
+
+
+def _apply_colorbar_defaults(fig: go.Figure, theme: Theme) -> None:
+    """Apply colorbar styling to all coloraxis."""
+    colorbar_cfg = dict(
+        orientation=theme.colorbar.orientation,
+        x=theme.colorbar.x,
+        y=theme.colorbar.y,
+        xanchor=theme.colorbar.xanchor,
+        yanchor=theme.colorbar.yanchor,
+        thickness=theme.colorbar.thickness,
+        len=theme.colorbar.len,
+        tickfont=dict(
+            size=theme.typography.tick_font_size,
+            family=theme.typography.font_family,
+        ),
+    )
+
+    for attr in dir(fig.layout):
+        if attr.startswith("coloraxis"):
+            coloraxis = getattr(fig.layout, attr)
+            colorbar = getattr(coloraxis, "colorbar", None)
+            if colorbar is None:
+                coloraxis.update(dict(colorbar=colorbar_cfg))
+            else:
+                colorbar.update(colorbar_cfg)

diffract/viz/styling/theme/components.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class LayoutStyle:
+    """Figure layout dimensions and margins."""
+
+    width: int | None = None
+    height: int | None = None
+    margin: dict[str, int] = field(
+        default_factory=lambda: {"l": 80, "r": 40, "t": 60, "b": 80}
+    )
+
+
+@dataclass
+class TypographyStyle:
+    """Font settings for the figure."""
+
+    font_family: str = "Times New Roman"
+    title_font_size: int = 16
+    label_font_size: int = 14
+    tick_font_size: int = 12
+
+
+@dataclass
+class BackgroundStyle:
+    """Background colors for the figure."""
+
+    plot_bgcolor: str = "white"
+    paper_bgcolor: str = "white"
+
+
+@dataclass
+class AxesStyle:
+    """Default axes styling (can be overridden by SupportsAxis fields)."""
+
+    grid_color: str = "lightgrey"
+    line_color: str = "black"
+    show_grid: bool = True
+    show_line: bool = True
+    mirror: bool = True
+
+
+@dataclass
+class LegendStyle:
+    """Legend styling."""
+
+    bgcolor: str = "rgba(255,255,255,0.9)"
+    border_color: str = "gray"
+    border_width: int = 1
+    font_size: int = 12
+
+
+@dataclass
+class ColorbarStyle:
+    """Colorbar positioning and appearance."""
+
+    orientation: str = "h"
+    x: float = 0.5
+    y: float = -0.15
+    xanchor: str = "center"
+    yanchor: str = "top"
+    thickness: int = 15
+    len: float = 0.5