dara-components 1.8.5__py3-none-any.whl → 1.22.1__py3-none-any.whl

dara/components/common/slider.py

@@ -15,14 +15,49 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from decimal import Decimal
-from typing import Any, Dict, List, Optional, Union
+from decimal import ROUND_FLOOR, Decimal
+from typing import Any
 
-from pydantic import validator
+from pydantic import Field, ValidationInfo, field_validator
 
 from dara.components.common.base_component import FormComponent
 from dara.core.base_definitions import Action
-from dara.core.interactivity import UrlVariable, Variable
+from dara.core.interactivity import Variable
+
+
+def compute_step(difference: Decimal) -> Decimal:
+    """
+    Compute what step should be used for the given domain difference.
+
+    The step is computed as:
+      step = 10^(floor(log10(difference))) / 10
+
+    For cases where the step is a decimal (i.e. when the log10 is negative),
+    the result is quantized to a fixed number of decimal places to avoid
+    floating point imprecision.
+
+    :param difference: The domain difference (must be positive).
+    :return: The computed step.
+    """
+    if difference <= 0:
+        raise ValueError('difference must be a positive Decimal.')
+
+    # Compute the base-10 logarithm of the difference
+    log_value = difference.log10()
+    # Get the integer part via floor
+    log_int = int(log_value.to_integral_value(rounding=ROUND_FLOOR))
+
+    # Compute 10^(floor(log10(difference))) / 10
+    step = (Decimal(10) ** log_int) / Decimal(10)
+
+    # If the logarithm is negative, quantize the step to prevent
+    # precision errors. The precision is set to abs(log_int) + 1 decimal places.
+    if log_int < 0:
+        num_decimals = abs(log_int) + 1
+        quantizer = Decimal(f'1e-{num_decimals}')
+        step = step.quantize(quantizer)
+
+    return step
 
 
 class Slider(FormComponent):
@@ -36,25 +71,26 @@ class Slider(FormComponent):
     A simple Slider component with a single handle that tracks the selected value over a given range is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Slider
 
+    value_var = Variable(0.5)
+
     Slider(
         domain=[0.0, 1.0],
-        value=Variable(0.5),
+        value=value_var,
     )
-
     ```
 
     A more complex example with multiple handles, a set step size, specified ticks, a right hand rail and a track label
     is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Slider
 
+    value_var = Variable([-3, 6, 8])
+
     Slider(
         domain=[-10, 10],
         step=2,
@@ -62,24 +98,23 @@ class Slider(FormComponent):
         rail_labels=['My Slider'],
         rail_to_end=True,
         ticks=[-9, -5, -1, 1, 5, 9],
-        value=Variable([-3, 6, 8]),
+        value=value_var,
     )
-
     ```
 
     Setting the disable_input_alternative to True removes the switch for changing the slider to a numerical input box:
 
     ```python
-
     from dara.core.definitions import Variable
     from dara.components.common import Slider
 
+    value_var = Variable(0.5)
+
     Slider(
         domain=[0.0, 1.0],
-        value=Variable(0.5),
+        value=value_var,
         disable_input_alternative=True,
     )
-
     ```
 
     :param domain: The range of the slider
@@ -88,26 +123,28 @@ class Slider(FormComponent):
     :param rail_from_start:  Boolean, if True the track is rendered from leftmost handle to the end
     :param rail_labels: A label for the track
     :param rail_to_end: Boolean, if True the track is rendered from rightmost handle to the end
+    :param thumb_labels: A list of labels for the slider's thumbs
     :param ticks: List specifying the position of the ticks
     :param value: A Variable instance recording the component's state; can be a single number for single-handle Slider, or an N-length array for a Slider with N handles
     :param disable_input_alternative: Boolean, if True disable the rendering of the input alternative switch
     :param id: the key to be used if this component is within a form
     """
 
-    domain: List[float]
-    onchange: Optional[Action] = None
-    step: Optional[float] = None
+    domain: list[float]
+    onchange: Action | None = None
+    step: float | None = Field(None, validate_default=True)
     rail_from_start: bool = True
-    rail_labels: Optional[List[str]] = None
+    rail_labels: list[str] | None = None
     rail_to_end: bool = False
-    ticks: Optional[List[Union[float, int]]] = None
-    value: Optional[Union[Variable[Any], UrlVariable[Any]]] = None
+    thumb_labels: list[str] | None = None
+    ticks: list[float | int] | None = None
+    value: Variable[Any] | None = None
     disable_input_alternative: bool = False
-    id: Optional[str] = None
+    id: str | None = None
 
-    @validator('domain')
+    @field_validator('domain')
     @classmethod
-    def domain_valid(cls, v: List[float]) -> List[float]:
+    def domain_valid(cls, v: list[float]) -> list[float]:
         if len(v) != 2:
             raise ValueError(f'Domain must be a list of length two [min, max], found {v}')
 
@@ -116,22 +153,30 @@ class Slider(FormComponent):
 
         return v
 
-    @validator('step')
+    @field_validator('step')
     @classmethod
-    def step_valid(cls, v: Optional[float], values: Dict[str, Any]) -> Optional[float]:
-        if v is None:
+    def step_valid(cls, v: float | None, info: ValidationInfo) -> float | None:
+        # domain validation must have failed, skip
+        if 'domain' not in info.data:
             return v
 
-        # both step and domain are set, make sure they are compatible
+        # make sure step and domain are compatible
         # using Decimal to avoid floating point errors
-        domain = values['domain']
+        domain = info.data['domain']
         domain_range = Decimal(str(domain[1])) - Decimal(str(domain[0]))
-        step = Decimal(str(v))
+
+        # If step is not provided, run inference to check if the
+        # client-side computed step is compatible with the domain range.
+        # The actual step is computed in the client-side but we check it here to fail early.
+        step = compute_step(domain_range) if v is None else Decimal(str(v))
 
         # Not divisible
         if domain_range % step != 0:
+            step_string = f'Step {step}'
+            if v is None:
+                step_string += ' (inferred from domain range)'
             raise ValueError(
-                f'Step {v} is not compatible with domain {domain}. The domain range must be divisible by the step provided.'
+                f'{step_string} is not compatible with domain {domain}. The domain range must be divisible by the step.'
             )
 
         return v

dara/components/common/spacer.py

@@ -15,9 +15,7 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Union
-
-from pydantic import validator
+from pydantic import field_validator
 
 from dara.components.common.base_component import ContentComponent
 
@@ -84,10 +82,10 @@ class Spacer(ContentComponent):
     """
 
     line: bool = False
-    size: Union[int, str] = '0.75rem'
-    inset: Union[int, str] = '0rem'
+    size: int | str = '0.75rem'
+    inset: int | str = '0rem'
 
-    @validator('size', 'inset')
+    @field_validator('size', 'inset')
     @classmethod
     def validate_dimension(cls, value):
         if isinstance(value, int):

dara/components/common/stack.py

@@ -16,7 +16,6 @@ limitations under the License.
 """
 
 import logging
-from typing import Union
 
 from dara.components.common.base_component import LayoutComponent
 from dara.core.definitions import ComponentInstance
@@ -123,6 +122,10 @@ class Stack(LayoutComponent):
 
     ```
 
+    Important: when using `For` component with `virtualization` enabled, do not use the Stack `scroll` argument,
+    as it is redundant and will result in unexpected behavior. The `For` component will automatically handle scrolling
+    for you.
+
     :param direction: The direction to stack children, can be 'vertical' or 'horizontal', default is 'vertical'
     :param collapsed: Whether to collapse the stack
     :param justify: How to justify the content of the stack, accepts any flexbox justifications
@@ -131,11 +134,11 @@ class Stack(LayoutComponent):
     :param scroll: Whether to scroll the content of the stack, defaults to False
     """
 
-    collapsed: Union[Variable[bool], bool] = False
+    collapsed: Variable[bool] | bool = False
     direction: Direction = Direction.VERTICAL
-    hug: bool = False
+    hug: bool | None = False
     scroll: bool = False
 
     # Dummy init that just passes through arguments to superclass, fixes Pylance complaining about types
-    def __init__(self, *args: ComponentInstance, **kwargs):
+    def __init__(self, *args: ComponentInstance | None, **kwargs):
         super().__init__(*args, **kwargs)

dara/components/common/switch.py

@@ -15,11 +15,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Optional, Union
-
 from dara.components.common.base_component import FormComponent
 from dara.core.base_definitions import Action
-from dara.core.interactivity import UrlVariable, Variable
+from dara.core.interactivity import Variable
 
 
 class Switch(FormComponent):
@@ -31,12 +29,12 @@ class Switch(FormComponent):
     A Switch component is created via:
 
     ```python
-
     from dara.core import Variable
     from dara.components.common import Switch
 
-    Switch(value=Variable(default=True))
+    value_var = Variable(default=True)
 
+    Switch(value=value_var)
     ```
 
     :param value: Boolean Variable instance recording the component's state
@@ -44,6 +42,6 @@ class Switch(FormComponent):
     :param id: the key to be used if this component is within a form
     """
 
-    value: Optional[Union[Variable[bool], UrlVariable[bool]]] = None
-    onchange: Optional[Action] = None
-    id: Optional[str] = None
+    value: Variable[bool] | None = None
+    onchange: Action | None = None
+    id: str | None = None

dara/components/common/tabbed_card.py

@@ -15,10 +15,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 """
 
-from typing import Optional
-
 from dara.components.common.base_component import LayoutComponent
-from dara.core.interactivity import NonDataVariable
+from dara.core.interactivity import ClientVariable
 
 
 class TabbedCard(LayoutComponent):
@@ -29,8 +27,7 @@ class TabbedCard(LayoutComponent):
 
     A tabbed card component can be created via:
 
-     ```python
-
+    ```python
     from dara.components.common import Tab, TabbedCard, Text
 
     TabbedCard(
@@ -43,8 +40,7 @@ class TabbedCard(LayoutComponent):
             title='Tab 2'
         )
     )
-
-     ```
+    ```
 
     A tabbed card component where the tab is controlled by a Variable:
 
@@ -52,20 +48,21 @@ class TabbedCard(LayoutComponent):
     from dara.core import Variable
     from dara.components.common import Tab, TabbedCard, Text
 
+    tab_var = Variable('Tab 2')
+
     TabbedCard(
         Tab(Text('Some Text'), title='Tab 1'),
         Tab(Text('Some Text'), title='Tab 2'),
-        selected_tab=Variable('Tab 2'),
+        selected_tab=tab_var,
     )
-
     ```
 
     :param initial_tab: Optional title of the tab to initially render, defaults to the first
     :param selected_tab: Optional selected tab mapped to a variable so that the selected tab can be easily accessed
     """
 
-    initial_tab: Optional[str] = None
-    selected_tab: Optional[NonDataVariable] = None
+    initial_tab: str | None = None
+    selected_tab: ClientVariable | None = None
 
 
 class Tab(LayoutComponent):