from typing import Optional

from flet.controls.base_control import control
from flet.controls.control import Control

__all__ = ["AdaptiveControl"]


@control(kw_only=True)
class AdaptiveControl(Control):
    """
    Base class for controls that support adaptive behavior, which allows them to adjust
    their appearance and behavior based on the target platform (ex: Material design on Android/Windows/Linux,
    Cupertino design on iOS/macOS).

    The [`adaptive`][(c).] property is applicable in two common scenarios:

    1. **Platform-adaptive controls**:
       These controls have a corresponding version on both Material and Cupertino platforms.
       When `adaptive` is set to `True`, the control renders the appropriate platform-specific
       implementation.

    2. **Container controls**:
       Controls that contain children (ex: [`Row`][flet.Row], [`Column`][flet.Column]) can pass
       the `adaptive` value down to their children that do not explicitly define it themselves.
       This enables nested adaptive behavior in complex layouts.

    Extension developers can use this base class to create their own adaptive controls by
    checking the `adaptive` flag at runtime and rendering accordingly.

    Note:
        This class does not implement any platform-specific rendering itself.
        It is up to the control inheriting from it to interpret the [`adaptive`][(c).] flag and render accordingly.
    """
    adaptive: Optional[bool] = None
    """
    Enables platform-specific rendering or inheritance of adaptiveness from parent controls.
    """