xnano.components.component

Bases: ContentBase

Render grouped bars.

Attributes:

• groups (tuple[BarGroup, ...]) –

  Bar groups.

• bar_width (int) –

  Width of each bar in cells.

• bar_gap (int) –

  Cells between bars.

• group_gap (int) –

  Cells between groups.

• max_value (int | None) –

  Explicit value ceiling.

• direction (Direction) –

  Bar growth direction.

• color (ColorLike | None) –

  Default bar color.

• value_color (ColorLike | None) –

  Default value-label color.

• label_color (ColorLike | None) –

  Bar-label color.

style: Style | None = None

z: int = 0

visible: bool = True

groups: tuple[BarGroup, ...] = ()

bar_width: int = 1

bar_gap: int = 1

group_gap: int = 0

max_value: int | None = None

direction: Direction = 'vertical'

color: ColorLike | None = None

value_color: ColorLike | None = None

label_color: ColorLike | None = None

Bases: ContentBase

Render geometric shapes in numeric coordinate space.

Attributes:

• shapes (tuple[CanvasShape, ...]) –

  Shapes painted in declaration order.

• x_bounds (tuple[float, float]) –

  Horizontal coordinate bounds.

• y_bounds (tuple[float, float]) –

  Vertical coordinate bounds.

• marker (CanvasMarkerLike) –

  Canvas point marker.

• background (ColorLike | None) –

  Canvas background.

style: Style | None = None

z: int = 0

visible: bool = True

shapes: tuple[CanvasShape, ...] = ()

x_bounds: tuple[float, float] = (0.0, 1.0)

y_bounds: tuple[float, float] = (0.0, 1.0)

marker: CanvasMarkerLike = 'braille'

background: ColorLike | None = None

Bases: ContentBase

A rectangular sequence of styled cell rows.

Attributes:

• rows (tuple[tuple[CellSpan, ...], ...]) –

  Rows of styled spans.

• width (int) –

  Canvas width in cells.

• height (int) –

  Canvas height in cells.

style: Style | None = None

z: int = 0

visible: bool = True

rows: tuple[tuple[CellSpan, ...], ...] = ()

width: int = 0

height: int = 0

from_rows(
    rows: Sequence[Sequence[CellSpan | str]],
    *,
    width: int | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True
) -> "CellCanvas"

915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944

@classmethod
def from_rows(
    cls,
    rows: Sequence[Sequence[CellSpan | str]],
    *,
    width: int | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
) -> "CellCanvas":
    """Create a cell canvas from styled span rows."""
    normalized = tuple(
        tuple(
            span if isinstance(span, CellSpan) else CellSpan(text=span)
            for span in row
        )
        for row in rows
    )
    measured_width = max(
        (sum(len(span.text) for span in row) for row in normalized),
        default=0,
    )
    return cls(
        rows=normalized,
        width=measured_width if width is None else width,
        height=len(normalized),
        style=style,
        z=z,
        visible=visible,
    )

Bases: ContentBase

Clear the assigned render area.

Attributes:

• style (Style | None) –

  Optional shared style.

• z (int) –

  Sibling-local paint order.

• visible (bool) –

  Whether this content paints.

style: Style | None = None

z: int = 0

visible: bool = True

Bases: ContentBase

Render a filled progress gauge.

Attributes:

• progress (float) –

  Completion ratio from zero to one.

• label (str | None) –

  Text displayed inside the gauge.

• foreground (ColorLike) –

  Filled-region color.

• background (ColorLike | None) –

  Gauge background color.

style: Style | None = None

z: int = 0

visible: bool = True

progress: float = 0.0

label: str | None = None

foreground: ColorLike = 'green'

background: ColorLike | None = None

Bases: ContentBase

Render a selectable list of text items.

Attributes:

• items (tuple[str | Run | TextBlock, ...]) –

  List entries.

• selected (int | None) –

  Selected entry index.

• foreground (ColorLike | None) –

  Default foreground.

• background (ColorLike | None) –

  Default background.

• highlight_color (ColorLike) –

  Selected-entry foreground.

• highlight_background (ColorLike) –

  Selected-entry background.

• highlight_symbol (str) –

  Symbol prefixed to the selected entry.

style: Style | None = None

z: int = 0

visible: bool = True

items: tuple[str | Run | TextBlock, ...] = ()

selected: int | None = None

foreground: ColorLike | None = None

background: ColorLike | None = None

highlight_color: ColorLike = 'black'

highlight_background: ColorLike = 'white'

highlight_symbol: str = '> '

Bases: ContentBase

Render progress as a single horizontal line.

Attributes:

• progress (float) –

  Completion ratio from zero to one.

• label (str | None) –

  Text displayed with the line.

• foreground (ColorLike | None) –

  Default foreground color.

• filled_color (ColorLike | None) –

  Completed-region color.

• unfilled_color (ColorLike | None) –

  Remaining-region color.

• background (ColorLike | None) –

  Line background color.

style: Style | None = None

z: int = 0

visible: bool = True

progress: float = 0.0

label: str | None = None

foreground: ColorLike | None = None

filled_color: ColorLike | None = None

unfilled_color: ColorLike | None = None

background: ColorLike | None = None

Bases: ContentBase

Decorate child content with a frame and padding.

Attributes:

• child (ContentBase) –

  Content inside the panel.

• title (str | None) –

  Optional frame title.

• title_position (FrameTitlePosition | None) –

  Frame title alignment.

• border (Border | None) –

  Border style.

• border_color (ColorLike | None) –

  Border foreground color.

• border_sides (tuple[Side, ...] | None) –

  Visible border sides.

• background (ColorLike | None) –

  Panel background color.

• padding (PaddingLike | None) –

  Space between border and child.

style: Style | None = None

z: int = 0

visible: bool = True

child: ContentBase

title: str | None = None

title_position: FrameTitlePosition | None = None

border: Border | None = None

border_color: ColorLike | None = None

border_sides: tuple[Side, ...] | None = None

background: ColorLike | None = None

padding: PaddingLike | None = None

Bases: ContentBase

Render one or more numeric data series.

Attributes:

• datasets (tuple[PlotDataset, ...]) –

  Data series.

• x_axis (PlotAxis | None) –

  Horizontal axis.

• y_axis (PlotAxis | None) –

  Vertical axis.

• color (ColorLike | None) –

  Default plot color.

• legend (bool) –

  Whether to show the legend.

• legend_position (LegendPositionLike | None) –

  Legend placement.

style: Style | None = None

z: int = 0

visible: bool = True

datasets: tuple[PlotDataset, ...] = ()

x_axis: PlotAxis | None = None

y_axis: PlotAxis | None = None

color: ColorLike | None = None

legend: bool = True

legend_position: LegendPositionLike | None = 'top_right'

Bases: ContentBase

One styled text run.

Attributes:

• text (str) –

  Text displayed by the run.

• foreground (ColorLike | None) –

  Foreground color.

• background (ColorLike | None) –

  Background color.

• modifiers (tuple[CharacterModifier, ...]) –

  Character modifiers.

style: Style | None = None

z: int = 0

visible: bool = True

text: str

foreground: ColorLike | None = None

background: ColorLike | None = None

modifiers: tuple[CharacterModifier, ...] = ()

__post_init__(color: Any) -> None

83
84
85

def __post_init__(self, color: Any) -> None:
    """Apply the deprecated constructor alias."""
    resolve_init_alias(self, color, old="color", new="foreground")

plain(
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "Run"

 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124

@classmethod
def plain(
    cls,
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "Run":
    """Create a plain styled run.

    Args:
        text: Text displayed by the run.
        foreground: Foreground color.
        background: Background color.
        modifiers: Character modifiers.
        style: Optional shared style.
        z: Sibling-local paint order.
        visible: Whether the run paints.
        color: Deprecated alias for ``foreground``.

    Returns:
        A run containing ``text``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    return cls(
        text=text,
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        style=style,
        z=z,
        visible=visible,
    )

Bases: ContentBase

Render a compact sequence of vertical samples.

Attributes:

• data (tuple[int, ...]) –

  Sample values.

• bars (tuple[SparklineBar, ...] | None) –

  Individually styled samples.

• max_value (int | None) –

  Explicit sample ceiling.

• foreground (ColorLike | None) –

  Default sample color.

• background (ColorLike | None) –

  Sparkline background.

• absent_value_color (ColorLike | None) –

  Color for missing or zero samples.

• absent_value_symbol (str | None) –

  Symbol for missing or zero samples.

style: Style | None = None

z: int = 0

visible: bool = True

data: tuple[int, ...] = ()

bars: tuple[SparklineBar, ...] | None = None

max_value: int | None = None

foreground: ColorLike | None = None

background: ColorLike | None = None

absent_value_color: ColorLike | None = None

absent_value_symbol: str | None = None

Bases: ContentBase

Lay out child content in one direction.

Attributes:

• children (tuple[ContentBase, ...]) –

  Child content.

• direction (Direction) –

  Layout direction.

• gap (int) –

  Cells between children.

style: Style | None = None

z: int = 0

visible: bool = True

children: tuple[ContentBase, ...] = ()

direction: Direction = 'vertical'

gap: int = 0

Bases: ContentBase

Render tabular rows with optional selection.

Attributes:

• rows (tuple[TableRow, ...]) –

  Body rows.

• header (TableRow | None) –

  Optional header row.

• footer (TableRow | None) –

  Optional footer row.

• column_widths (tuple[int | float, ...] | None) –

  Fixed cell widths or fractional widths.

• column_spacing (int) –

  Cells between columns.

• selected_row (int | None) –

  Selected body row.

• selected_column (int | None) –

  Selected column.

• highlight_color (ColorLike | None) –

  Selection foreground.

• highlight_background (ColorLike | None) –

  Selection background.

• highlight_symbol (str | None) –

  Symbol prefixed to the selected row.

style: Style | None = None

z: int = 0

visible: bool = True

rows: tuple[TableRow, ...] = ()

header: TableRow | None = None

footer: TableRow | None = None

column_widths: tuple[int | float, ...] | None = None

column_spacing: int = 1

selected_row: int | None = None

selected_column: int | None = None

highlight_color: ColorLike | None = None

highlight_background: ColorLike | None = None

highlight_symbol: str | None = None

Bases: ContentBase

Wrapped plain text or lines of styled runs.

Attributes:

• text (str) –

  Plain text content.

• lines (tuple[tuple[Run, ...], ...]) –

  Styled text lines.

• foreground (ColorLike | None) –

  Default foreground color.

• background (ColorLike | None) –

  Default background color.

• modifiers (tuple[CharacterModifier, ...]) –

  Default character modifiers.

• horizontal_align (Alignment | None) –

  Horizontal alignment.

• vertical_align (VerticalAlignment | None) –

  Vertical alignment within the painted area.

• wrap (bool) –

  Whether long lines wrap.

style: Style | None = None

z: int = 0

visible: bool = True

text: str = ''

lines: tuple[tuple[Run, ...], ...] = ()

foreground: ColorLike | None = None

background: ColorLike | None = None

modifiers: tuple[CharacterModifier, ...] = ()

horizontal_align: Alignment | None = None

vertical_align: VerticalAlignment | None = None

wrap: bool = True

__post_init__(color: Any, align: Any) -> None

168
169
170
171

def __post_init__(self, color: Any, align: Any) -> None:
    """Apply deprecated constructor aliases."""
    resolve_init_alias(self, color, old="color", new="foreground")
    resolve_init_alias(self, align, old="align", new="horizontal_align")

from_plain(
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "TextBlock"

173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

@classmethod
def from_plain(
    cls,
    text: str,
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "TextBlock":
    """Create a block from plain text and explicit style values.

    ``color`` is a deprecated alias for ``foreground``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    return cls(
        text=text,
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        wrap=wrap,
        style=style,
        z=z,
        visible=visible,
    )

from_lines(
    lines: Sequence[Sequence[Run] | Run | str],
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None
) -> "TextBlock"

207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

@classmethod
def from_lines(
    cls,
    lines: Sequence[Sequence[Run] | Run | str],
    *,
    foreground: ColorLike | None = None,
    background: ColorLike | None = None,
    modifiers: Sequence[CharacterModifier] | None = None,
    horizontal_align: Alignment | None = None,
    vertical_align: VerticalAlignment | None = None,
    wrap: bool = True,
    style: Style | None = None,
    z: int = 0,
    visible: bool = True,
    color: ColorLike | None = None,
) -> "TextBlock":
    """Create a block from styled line sequences.

    ``color`` is a deprecated alias for ``foreground``.
    """
    foreground = resolve_color_alias(foreground, color, stacklevel=3)
    normalized: list[tuple[Run, ...]] = []
    for line in lines:
        if isinstance(line, str):
            normalized.append((Run(text=line),))
        elif isinstance(line, Run):
            normalized.append((line,))
        else:
            normalized.append(tuple(line))
    return cls(
        lines=tuple(normalized),
        foreground=foreground,
        background=background,
        modifiers=tuple(modifiers or ()),
        horizontal_align=horizontal_align,
        vertical_align=vertical_align,
        wrap=wrap,
        style=style,
        z=z,
        visible=visible,
    )