hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/components/progress_bar.py

@@ -0,0 +1,70 @@
+from ..prop_types import CSSField, ClampedFloat, Bool, String, Color, Size
+from ..prop import Prop
+from .common.label_component import LabelComponent
+from ..style_part import BasePart, StylePart
+from .common.shoelace_types import ProgressTrackColor, ProgressIndicatorColor
+
+
+class progress_bar(LabelComponent):
+    """
+    Renders a progress bar that can be either indeterminate, or have a
+    concrete percentage value.
+
+    ### Indeterminate
+
+    ```py
+    hd.progress_bar(indeterminate=True)
+    ```
+
+    ### Concrete value
+
+    ```py
+    hd.progress_bar(value=40)
+    ```
+
+    ### Custom progress bar
+
+    ```py
+    hd.progress_bar(
+        "40%",
+        value=40,
+        track_color="blue-50",
+        indicator_color="green-300",
+        label_color="yellow",
+        bar_height=4,
+        label_style=hd.style(
+            font_size=2,
+            font_family="mono"
+        ),
+    )
+    ```
+
+    ### Mutating the value
+
+    ```py
+    with hd.box(gap=1):
+        bar = hd.progress_bar(value=40)
+        with hd.hbox(gap=1):
+            if hd.button("Increase").clicked:
+                if bar.value <= 95:
+                    bar.value += 5
+            if hd.button("Reset").clicked:
+                    bar.value = 40
+    ```
+
+    """
+
+    _name = "progress_bar"
+    _tag = "sl-progress-bar"
+
+    value = Prop(ClampedFloat(0, 100), 0)
+    indeterminate = Prop(Bool, False)
+    assistive_label = Prop(String, "", ui_name="label")
+    bar_height = Prop(CSSField("--height", Size))
+    track_color = Prop(ProgressTrackColor)
+    indicator_color = Prop(ProgressIndicatorColor)
+    label_color = Prop(CSSField("--label-color", Color))
+
+    base_style = Prop(BasePart())
+    indicator_style = Prop(StylePart("indicator"))
+    label_style = Prop(StylePart("label"))

hyperdiv/components/progress_ring.py

@@ -0,0 +1,57 @@
+from ..prop_types import CSSField, Optional, String, Size, Int, TimeValue
+from ..prop import Prop
+from ..style_part import BasePart, StylePart
+from .common.label_component import LabelComponent
+from .common.shoelace_types import (
+    ProgressTrackColor,
+    ProgressIndicatorColor,
+    ProgressTrackWidth,
+)
+
+
+class progress_ring(LabelComponent):
+    """
+    A customizable circular progress component that can be used to
+    indicate progress to the user.
+
+    ```py
+    with hd.box(gap=0.5):
+        progress = hd.progress_ring(value=10)
+        with hd.hbox():
+            minus = hd.icon_button("dash")
+            if minus.clicked:
+                progress.value -= 10
+            plus = hd.icon_button("plus")
+            if plus.clicked:
+                progress.value += 10
+    ```
+
+    """
+
+    _name = "progress_ring"
+    _tag = "sl-progress-ring"
+
+    # The value of the progress ring. 0 indicates an empty ring, and
+    # 100 indicates a full ring. Negative values or values over 100
+    # will cause the ring to wrap around.
+    value = Prop(Int, 0)
+    # An invisible label useful for accessibility.
+    assistive_label = Prop(String, "", ui_name="label")
+    # The width of the background track.
+    track_width = Prop(ProgressTrackWidth)
+    # The color of the background track.
+    track_color = Prop(ProgressTrackColor)
+    # The width of the progress indicator.
+    indicator_width = Prop(CSSField("--indicator-width", Size))
+    # The color of the progress indicator.
+    indicator_color = Prop(ProgressIndicatorColor)
+    # The diameter of the progress ring.
+    size = Prop(CSSField("--size", Size), 4)
+    # How long it takes to visually transition from the current value
+    # to the new value, when the value changes.
+    transition_duration = Prop(
+        CSSField("--indicator-transition-duration", Optional(TimeValue))
+    )
+
+    base_style = Prop(BasePart())
+    label_style = Prop(StylePart("label"))

hyperdiv/components/radio.py

@@ -0,0 +1,40 @@
+from ..prop_types import String, Optional, Bool
+from ..prop import Prop
+from ..style_part import BasePart, StylePart
+from .common.text_utils import concat_text
+from .common.label_component import LabelComponent
+from .common.shoelace_types import ShoelaceSize
+
+
+class radio(LabelComponent):
+    """
+    A radio input component to be used with @component(radio_group).
+    It isn't useful by itself.
+
+    ```py
+    r = hd.radio("A radio button")
+    ```
+    """
+
+    _name = "radio"
+    _tag = "sl-radio"
+
+    # The value of the radio button. By default, the value is set to
+    # be equal to the label, if the value prop is not given.
+    value = Prop(Optional(String))
+    # The size of the radio button.
+    size = Prop(ShoelaceSize, "medium")
+    # Whether the radio button can be selected.
+    disabled = Prop(Bool, False)
+
+    base_style = Prop(BasePart())
+    control_style = Prop(StylePart("control"))
+    control_checked_style = Prop(StylePart("control--checked"))
+    checked_icon_style = Prop(StylePart("checked-icon"))
+    label_style = Prop(StylePart("label"))
+
+    def __init__(self, *label, value=None, **kwargs):
+        if value is None:
+            value = concat_text(label)
+
+        super().__init__(*label, value=value, **kwargs)

hyperdiv/components/radio_button.py

@@ -0,0 +1,51 @@
+from ..prop_types import String, Optional, Bool
+from ..prop import Prop
+from ..slot import Slot
+from ..style_part import BasePart, StylePart
+from .common.text_utils import concat_text
+from .common.label_component import LabelComponent
+from .common.shoelace_types import ShoelaceSize
+
+
+class radio_button(LabelComponent):
+    """
+    A radio button component to be used with
+    @component(radio_group). Similar to @component(radio), but
+    rendered as a button.
+
+    This component isn't useful by itself and should only be used when
+    nested in a @component(radio_group).
+
+    ```py
+    hd.radio_button("My Button")
+    ```
+    """
+
+    _name = "radio_button"
+    _tag = "sl-radio-button"
+
+    # The value of the radio button. By default, if `value` isn't
+    # provided, it is set to be equal to the label.
+    value = Prop(Optional(String))
+    # The size of the radio button.
+    size = Prop(ShoelaceSize, "medium")
+    # Whether this radio button can be selected.
+    disabled = Prop(Bool, False)
+    # Whether to render the radio button as a pill.
+    pill = Prop(Bool, False)
+
+    prefix = Slot()
+    suffix = Slot()
+
+    base_style = Prop(BasePart())
+    button_style = Prop(StylePart("button"))
+    button_checked_style = Prop(StylePart("button--checked"))
+    prefix_style = Prop(StylePart("prefix"))
+    label_style = Prop(StylePart("label"))
+    suffix_style = Prop(StylePart("suffix"))
+
+    def __init__(self, *label, value=None, width="fit-content", **kwargs):
+        if value is None:
+            value = concat_text(label)
+
+        super().__init__(*label, value=value, width=width, **kwargs)

hyperdiv/components/radio_group.py

@@ -0,0 +1,167 @@
+from ..prop_types import String, BoolEvent, Bool
+from ..prop import Prop
+from ..component_base import Component
+from ..component_mixins.styled import Styled
+from ..style_part import BasePart, StylePart
+from .common.text_utils import concat_text
+from .radio import radio
+from .radio_button import radio_button
+from .scope import scope
+
+
+class radio_group(Component, Styled):
+    """
+    An exclusive choice component, allowing the user to select one
+    from multiple choices. @component(radio)s and
+    @component(radio_button)s can be nested within a `radio_group`.
+
+    ### Radios
+
+    ```py
+    with hd.box(gap=1):
+        with hd.radio_group(value="One") as group:
+            hd.radio("One")
+            hd.radio("Two")
+            hd.radio("Three")
+
+        hd.text("Selected:", group.value)
+    ```
+
+    ### Radio buttons
+
+    ```py
+    with hd.box(gap=1):
+        with hd.radio_group(value="One") as group:
+            hd.radio_button("One")
+            hd.radio_button("Two")
+            hd.radio_button("Three")
+
+        hd.text("Selected:", group.value)
+    ```
+
+    Using the `pill` option to make a rounded radio button group:
+
+    ```py
+    with hd.box(gap=1):
+        with hd.radio_group(value="One") as group:
+            hd.radio_button("One", pill=True)
+            hd.radio_button("Two")
+            hd.radio_button("Three", pill=True)
+
+        hd.text("Selected:", group.value)
+    ```
+
+    ### Shorthand syntax
+
+    Radio groups can be quickly created in one shot by passing the `options` kwarg.
+
+    ```py
+    hd.radio_group(
+        options=("One", "Two", "Three"),
+        value="One"
+    )
+    ```
+
+    Similarly, by passing `button_options` to create button groups:
+
+    ```py
+    hd.radio_group(
+        button_options=("One", "Two", "Three"),
+        value="One"
+    )
+    ```
+
+    In addition, the helper functions `radios` and `radio_buttons` are provided:
+
+    ```py
+    with hd.box(gap=1):
+        hd.radios(
+            "One", "Two", "Three",
+            value="One"
+        )
+        hd.radio_buttons(
+            "One", "Two", "Three",
+            value="One"
+        )
+    ```
+    """
+
+    _name = "radio_group"
+    _tag = "sl-radio-group"
+
+    # The visible label of the group.
+    label = Prop(String, "")
+    # The name of the group. By default, if `name` is not provided, it
+    # is set to the label of the group.
+    name = Prop(String, "")
+    # The value of the nested @component(radio) or
+    # @component(radio_button) that is currently selected.
+    value = Prop(String, "")
+    # A small text hint further describing the radio group.
+    help_text = Prop(String, "")
+    # Whether the value of the radio group changed.
+    changed = Prop(BoolEvent, False)
+    # If this prop is True, the @component(radio) and
+    # @component(radio_button) children of this radio group will be
+    # disabled.
+    disabled = Prop(Bool, False)
+
+    base_style = Prop(BasePart("form-control"))
+    label_style = Prop(StylePart("form-control-label"))
+    input_wrapper_style = Prop(StylePart("form-control-input"))
+    help_text_style = Prop(StylePart("form-control-help-text"))
+    button_group_wrapper_style = Prop(StylePart("button-group"))
+    button_group_style = Prop(StylePart("button-group__base"))
+
+    def __init__(
+        self,
+        *label_args,
+        options=None,
+        button_options=None,
+        name=None,
+        label="",
+        **kwargs,
+    ):
+        label = label or concat_text(label_args)
+        if name is None:
+            name = label
+
+        super().__init__(label=label, name=name, **kwargs)
+
+        if options is not None:
+            with self:
+                for o in options:
+                    with scope(o):
+                        radio(o)
+
+        if button_options is not None:
+            with self:
+                for o in button_options:
+                    with scope(o):
+                        radio_button(o)
+
+    def _collect_child(self, child):
+        if isinstance(child, (radio, radio_button)):
+            child.disabled = self.disabled
+        super()._collect_child(child)
+
+    def reset(self):
+        self.reset_prop("value")
+
+
+def radios(*options, label=None, **kwargs):
+    """
+    Creates a @component(radio_group) with the given label, with
+    nested @component(radio)s, one @component(radio) per item in
+    `options`.
+    """
+    return radio_group(label=label, options=options, **kwargs)
+
+
+def radio_buttons(*options, label=None, **kwargs):
+    """
+    Creates a @component(radio_group) with the given label, with
+    nested @component(radio_button)s, one @component(radio_button)
+    per item in `options`.
+    """
+    return radio_group(label=label, button_options=options, **kwargs)

hyperdiv/components/scope.py

@@ -0,0 +1,112 @@
+from contextlib import contextmanager
+from ..frame import AppRunnerFrame
+
+
+def scope(scope_id):
+    """
+    When creating components in loops, you will encounter this error:
+
+    ```py
+    for i in range(3):
+        hd.button("Button", i)
+    ```
+
+    To fix it, you wrap the loop body in `hd.scope(i)`, where `i`
+    uniquely identifies each iteration:
+
+    ```py
+    for i in range(3):
+        with hd.scope(i):
+            hd.button("Button", i)
+    ```
+
+    The reason behind having to use `scope` is that Hyperdiv
+    identifies each component uniquely based on the line number on
+    which it is constructed, in the code. In the first example, all
+    the buttons are constructed on the same line of code, so their
+    identifiers clash and Hyperdiv raises an error.
+
+    `hd.scope(i)` gives Hyperdiv extra "uniqueness" information to
+    include in the identifier. In this case, `i` is unique for each
+    loop iteration, allowing Hyperdiv to create unique identifiers for
+    the three buttons.
+
+    ## Choosing Good Scope IDs
+
+    Using the loop iteration index, like in the example above, is fine
+    for data that does not change. For data that can be sorted,
+    edited, or deleted, we need to use an identifier that is unique to
+    each data item.
+
+    ```py
+    state = hd.state(users=(
+        ("Mary", False),
+        ("Joe", False),
+        ("Amy", False)
+    ))
+
+    for i, (name, selected) in enumerate(state.users):
+        with hd.scope(i):
+            with hd.hbox():
+                hd.text(name, width=10)
+                hd.checkbox(checked=selected)
+
+    with hd.hbox(gap=1):
+        if hd.button("Reverse").clicked:
+            state.users = tuple(reversed(state.users))
+    ```
+
+    In the example above, we render a list of users along with
+    "selected" checkboxes associated with each user, in a loop wrapped
+    in `scope(i)`, which is the iteration index.
+
+    If you check the checkbox next to `Mary`, and then click `Reverse`,
+    the list will be reversed but `Amy` will now be wrongly
+    selected. This is because the checkbox identifier is derived from
+    `hd.scope(i)`, and `i` remains the same regardless of how the list
+    is sorted.
+
+    To fix this, we associate a unique user ID with each user record,
+    and use this ID as the scope ID:
+
+    ```py
+    state = hd.state(users=(
+        (123, "Mary", False),
+        (456, "Joe", False),
+        (789, "Amy", False)
+    ))
+
+    for user_id, name, selected in state.users:
+        with hd.scope(user_id):
+            with hd.hbox():
+                hd.text(name, width=10)
+                hd.checkbox(checked=selected)
+
+    with hd.hbox(gap=1):
+        if hd.button("Reverse").clicked:
+            state.users = tuple(reversed(state.users))
+    ```
+
+    When working with databases, this is an easy guideline to
+    follow. When rendering a list of database records, wrap the loop
+    body in a scope identified by each record's primary key:
+
+    ```py-nodemo
+    users = database.get_users()
+    for user in users:
+       with hd.scope(user.user_id):
+         render_user(user)
+    ```
+
+    """
+
+    @contextmanager
+    def scope_generator():
+        frame = AppRunnerFrame.current()
+        frame.push_scope(scope_id)
+        try:
+            yield
+        finally:
+            frame.pop_scope()
+
+    return scope_generator()

hyperdiv/components/select_.py

@@ -0,0 +1,151 @@
+from ..prop_types import String, Bool, OneOf, Union, PureString, List, Int, BoolEvent
+from ..prop import Prop
+from ..slot import Slot
+from ..component_mixins.togglable import Togglable
+from .common.shoelace_types import ShoelaceSize
+from ..style_part import BasePart, StylePart
+from .common.label_component import LabelComponent
+from .common.text_utils import concat_text
+from .option import option
+from .icon import icon
+from .scope import scope
+
+
+class select(LabelComponent, Togglable):
+    """
+    An input component that allows selecting one or more options from
+    a dropdown-style menu. Options within a `select` are created using
+    @component(option). @component(divider) can be used to insert
+    visual separation between option groups.
+
+    ### Single select
+
+    ```py
+    with hd.box(gap=1):
+        with hd.select(
+            placeholder="Choose One:"
+        ) as select:
+            hd.option("One")
+            hd.option("Two")
+            hd.divider()
+            hd.option("Three")
+            hd.option("Four")
+        hd.text("Selected:", select.value)
+    ```
+
+    ### Multi-select
+
+    When setting `multiple` to `True`, multiple items can be selected,
+    and the `value` prop outputs a list of all the selected values.
+
+    ```py
+    with hd.box(gap=1):
+        with hd.select(
+            placeholder="Choose Multiple:",
+            value=("One", "Two"),
+            multiple=True,
+        ) as select:
+            hd.option("One")
+            hd.option("Two")
+            hd.divider()
+            hd.option("Three")
+            hd.option("Four")
+        hd.text("Selected:", select.value)
+    ```
+
+    """
+
+    _name = "select"
+    _tag = "sl-select"
+
+    # The name of the select. Relevant when using select in a
+    # @component(form). Automatically set to the select's label if
+    # `name` is not specified.
+    name = Prop(String, "")
+    # The value of the select.
+    value = Prop(Union(PureString, List(String)), "")
+    # The size of the select.
+    size = Prop(ShoelaceSize, "medium")
+    # Ghost text to render in the select box when no items are
+    # selected.
+    placeholder = Prop(String, "")
+    # Whether this select is exclusive-choice or multiple choice.
+    multiple = Prop(Bool, False)
+    # The max number of options to render in the select when
+    # `multiple` is `True`.
+    max_options_visible = Prop(Int, 3)
+    # Whether this select can be interacted with.
+    disabled = Prop(Bool, False)
+    # Renders a clear button that allows clearing all the options in
+    # one click.
+    clearable = Prop(Bool, False)
+    hoist = Prop(Bool, False)
+    # Whether to render a filled-background select instead of an outline.
+    filled = Prop(Bool, False)
+    # Whether to render the select as a pill.
+    pill = Prop(Bool, False)
+    # Where to open the menu.
+    placement = Prop(OneOf("top", "bottom"), "bottom")
+    # A small text hint to render under the select.
+    help_text = Prop(String, "")
+    changed = Prop(BoolEvent, False)
+
+    label_slot = Slot(ui_name="label")
+    prefix = Slot()
+    clear_icon_slot = Slot(ui_name="clear-icon")
+    expand_icon_slot = Slot(ui_name="expand-icon")
+
+    base_style = Prop(BasePart("form-control"))
+    label_style = Prop(StylePart("form-control-label"))
+    help_text_style = Prop(StylePart("form-control-help-text"))
+    input_wrapper_style = Prop(StylePart("form-control-input"))
+    combobox_style = Prop(StylePart("combobox"))
+    prefix_style = Prop(StylePart("prefix"))
+    display_input_style = Prop(StylePart("display-input"))
+    listbox_style = Prop(StylePart("listbox"))
+    tags_style = Prop(StylePart("tags"))
+    tag_style = Prop(StylePart("tag"))
+    tag_base_style = Prop(StylePart("tag__base"))
+    tag_content_style = Prop(StylePart("tag__content"))
+    tag_remove_button_style = Prop(StylePart("tag__remove-button"))
+    tag_remove_button_base_style = Prop(StylePart("tag__remove-button__base"))
+    clear_button_style = Prop(StylePart("clear-button"))
+    expand_icon_style = Prop(StylePart("expand-icon"))
+
+    def __init__(
+        self,
+        *label,
+        options=None,
+        name=None,
+        prefix_icon=None,
+        clear_icon=None,
+        expand_icon=None,
+        **kwargs,
+    ):
+        """
+        If `options` is given as an iterable of option labels,
+        @component(option) components will be automatically created
+        for each given option.
+        """
+        if name is None:
+            name = concat_text(label)
+
+        super().__init__(*label, name=name, **kwargs)
+
+        with self:
+            if options:
+                for o in options:
+                    with scope(o):
+                        option(o, value=o.replace(" ", "_"))
+            if prefix_icon:
+                icon(prefix_icon, slot=self.prefix)
+            if clear_icon:
+                icon(clear_icon, slot=self.clear_icon_slot)
+            if expand_icon:
+                icon(expand_icon, slot=self.expand_icon_slot)
+
+    def reset(self):
+        self.reset_prop("value")
+
+    def _get_label_slot(self):
+        return self.label_slot