xnano.core.demo

def rebuild(self, width: int, height: int) -> None:
    """Rebuild and store the canvas for the current mode and phase."""
    self._size = (max(1, width), max(1, height))
    builder = _CANVAS_BUILDERS.get(self.mode, build_plasma_frame)
    self._canvas = builder(*self._size, self.phase)

def component_post_init(self) -> None:
    """Initialize subclass state after dataclass fields are assigned.

    Override this method instead of ``__post_init__``.
    """
    return None

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def get_size(self, ctx: ComponentRenderContext[StateT]) -> Size:
    """Return the preferred cell size of this component."""
    return Size(width=0, height=0)

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False

def component_post_init(self) -> None:
    """Initialize subclass state after dataclass fields are assigned.

    Override this method instead of ``__post_init__``.
    """
    return None

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def get_size(self, ctx: ComponentRenderContext[StateT]) -> Size:
    """Return the preferred cell size of this component."""
    return Size(width=0, height=0)

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False

def component_post_init(self) -> None:
    """Initialize subclass state after dataclass fields are assigned.

    Override this method instead of ``__post_init__``.
    """
    return None

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def get_size(self, ctx: ComponentRenderContext[StateT]) -> Size:
    """Return the preferred cell size of this component."""
    return Size(width=0, height=0)

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False

def select_tab(self, index: int) -> None:
    """Set the stage animation mode and force an immediate rebuild."""
    self.tab_index = index % len(_STAGE_MODES)
    self.view.mode = _STAGE_MODES[self.tab_index]
    self.view.rebuild(max(1, self.columns), max(1, self.rows))

def cycle_tab(self, delta: int) -> None:
    """Switch the stage animation mode by ``delta`` tabs."""
    self.select_tab(self.tab_index + delta)

def grid_get_field_state(self, name: str) -> FieldState | None:
    """Return tracked state for a field.

    Args:
        name: Field attribute name.

    Returns:
        Its state, or ``None`` for an unknown field.
    """
    return getattr(self, "_grid_field_states", {}).get(name)

def grid_mark_field_dirty(self, name: str) -> None:
    """Mark a field as changed.

    Args:
        name: Field attribute name.
    """
    state = self.grid_get_field_state(name)
    if state is not None:
        state.mark_dirty()
        state.value = getattr(self, name, None)

@warn_renamed_attribute(
    "AbstractInterface.get_field_state",
    "AbstractInterface.grid_get_field_state",
)
def get_field_state(self, name: str) -> FieldState | None:
    """Deprecated alias for ``grid_get_field_state``."""
    return self.grid_get_field_state(name)

@warn_renamed_attribute(
    "AbstractInterface.mark_field_dirty",
    "AbstractInterface.grid_mark_field_dirty",
)
def mark_field_dirty(self, name: str) -> None:
    """Deprecated alias for ``grid_mark_field_dirty``."""
    self.grid_mark_field_dirty(name)

def __post_init__(self) -> None:
    """Called at the end of the generated ``__init__``. Override to run post-construction logic."""

def grid_post_init(self) -> None:
    """Called exactly once, when this grid is first attached to a live
    terminal — after its own hooks are bound, before its first paint.

    Unlike ``__post_init__`` (construction time, no terminal attached
    yet), ``ctx``/``ctx.state`` are live here. Override with either
    signature — the extra parameter is optional, matching every other
    ``@on_*`` hook, dispatched by arity at runtime (see ``_call_hook``):

        def grid_post_init(self) -> None: ...
        def grid_post_init(self, ctx: Context[MyState]) -> None: ...

    A static type checker sees the one-parameter form as an invalid
    override (this base declares zero); that's a known false positive
    for this flexible-arity hook pattern — add
    ``# ty: ignore[invalid-method-override]`` on the override line.
    """

def grid_render(self) -> None:
    """Called each frame before layout.

    Override to refresh field values every frame. Initial values can be set
    with ``Field(default=...)``, ``default_factory``, or ``__post_init__``.

    Override with either signature — the extra ``Context`` parameter is
    optional, dispatched by arity like ``grid_post_init``:

        def grid_render(self) -> None: ...
        def grid_render(self, ctx: Context[MyState]) -> None: ...

    A static type checker sees the one-parameter form as an invalid
    override; add ``# ty: ignore[invalid-method-override]`` on the
    override line.
    """

@responsive_noop
def grid_render_extra_small(self) -> None:
    """Refine layout when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`grid_render`. Runs when
    the window enters this size tier — on the first render and on
    later resizes that cross into it — not every frame, so a
    per-frame ``@on_tick`` mutation is not overwritten by a size hook
    resetting the same field. Keep shared per-frame logic in
    ``grid_render`` and size-specific setup here. Overriding any
    ``grid_render_*`` variant opts the class into breakpoint dispatch;
    a class that overrides none pays no per-frame cost.
    """

@responsive_noop
def grid_render_small(self) -> None:
    """Refine layout when the viewport is small (40–79 cols).

    See :meth:`grid_render_extra_small`.
    """

@responsive_noop
def grid_render_medium(self) -> None:
    """Refine layout when the viewport is medium (80–119 cols).

    See :meth:`grid_render_extra_small`.
    """

@responsive_noop
def grid_render_large(self) -> None:
    """Refine layout when the viewport is large (120–159 cols).

    See :meth:`grid_render_extra_small`.
    """

@responsive_noop
def grid_render_extra_large(self) -> None:
    """Refine layout when the viewport is extra large (>= 160 cols).

    See :meth:`grid_render_extra_small`.
    """

@warn_renamed_attribute(
    "BaseGrid.grid_play_effect", "BaseGrid.grid_effect"
)
def grid_play_effect(
    self,
    effect: KnownEffectKind | AbstractEffect,
    *,
    duration_ms: int = 300,
    color: ColorLike | None = None,
    background: ColorLike | None = None,
    direction: EffectMotion | None = None,
    gradient_length: int | None = None,
    randomness: int | None = None,
    interpolation: EffectInterpolation | None = None,
    effects: Sequence[AbstractEffect] | None = None,
    child: AbstractEffect | None = None,
    times: int | None = None,
    fields: list[str] | None = None,
    key: str | None = None,
) -> bool:
    """Run a visual effect on one or more layout field areas.

    Each layout field is tagged with its name as an effect key during
    rendering, so effects can target field content rects on the frame
    after ``grid_render``.

    Pass a custom ``AbstractEffect`` subclass or
    provide a known effect kind with typed keyword arguments.

    Args:
        effect: A built effect instance or a known effect kind string.
        duration_ms: Duration of the effect in milliseconds.
        color: Foreground or accent color for color-driven effects.
        background: Background color for two-color effects.
        direction: Motion direction for slide and sweep effects.
        gradient_length: Gradient length for slide and sweep effects.
        randomness: Randomness for slide and sweep effects.
        interpolation: Interpolation curve for the effect.
        effects: Child effects for sequence and parallel composition.
        child: Child effect for repeat and delay composition.
        times: Repeat count for repeat effects.
        fields: Layout field names to target. When omitted or empty, no
            effect is started.
        key: Identity used to de-duplicate this effect per target
            field — see ``AbstractEffect.key``. Only meaningful when
            ``effect`` is a known-kind string; ignored when ``effect``
            is already a built ``AbstractEffect`` instance (set
            ``key`` on the instance itself in that case).

    Returns:
        ``True`` when at least one field area was found and an effect
        started.
    """
    return bool(
        self.grid_effect(
            effect,
            duration_ms=duration_ms,
            color=color,
            background=background,
            direction=direction,
            gradient_length=gradient_length,
            randomness=randomness,
            interpolation=interpolation,
            effects=effects,
            child=child,
            times=times,
            fields=fields,
            key=key,
        )
    )