hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/components/tests/tab_group_tests.py

@@ -0,0 +1,56 @@
+import pytest
+from ...test_utils import MockRunner, mock_frame
+from ...slot import Slot
+from ..tab_group import tab_group
+from ..tab import tab
+
+
+@mock_frame
+def test_tab_group():
+    with tab_group() as group:
+        tab("One")
+        tab("Two")
+
+    assert group.active == "One"
+    assert group.closed is None
+
+
+@mock_frame
+def test_tab_group_shorthand():
+    group = tab_group("One", "Two")
+    assert group.active == "One"
+    assert group.closed is None
+
+
+def test_select_tab():
+    t1_key = None
+    t2_key = None
+    group_key = None
+
+    def app():
+        nonlocal t1_key, t2_key, group_key
+
+        with tab_group() as group:
+            t1 = tab("One")
+            t1_key = t1._key
+
+            t2 = tab("Two")
+            t2_key = t2._key
+
+        group_key = group._key
+
+    with MockRunner(app) as mr:
+        assert mr.get_state(t1_key, "active") is True
+        assert mr.get_state(t2_key, "active") is False
+
+        mr.process_updates([(group_key, "_active_tab_key", t2_key)])
+
+        assert mr.get_state(t1_key, "active") is False
+        assert mr.get_state(t2_key, "active") is True
+
+
+@mock_frame
+def test_bad_slot():
+    with tab_group():
+        with pytest.raises(Exception):
+            tab("One", slot=Slot("Hello"))

hyperdiv/components/tests/tree_tests.py

@@ -0,0 +1,83 @@
+from ...test_utils import mock_frame, MockRunner
+from ..tree import tree
+from ..tree_item import tree_item
+from ..plaintext import plaintext
+from ..icon import icon
+
+
+@mock_frame
+def test_tree():
+    with tree(expand_icon_name="chevron-left", collapse_icon_name="chevron-right") as t:
+        ti = tree_item("One")
+        assert ti.label == "One"
+
+        ti = tree_item("Two", disabled=True)
+        assert ti.label == "Two"
+        assert isinstance(ti.children[0], plaintext) and ti.children[0].content == "Two"
+        assert ti.disabled
+
+        ti = tree_item("Three", expand_icon_name="robot", collapse_icon_name="table")
+        assert ti.label == "Three"
+        assert isinstance(ti.children[1], icon)
+        assert ti.children[1].name == "robot"
+        assert ti.children[1].slot == t.expand_icon
+
+        assert isinstance(ti.children[2], icon)
+        assert ti.children[2].name == "table"
+        assert ti.children[2].slot == t.collapse_icon
+
+    assert isinstance(t.children[0], icon)
+    assert t.children[0].name == "chevron-left"
+    assert isinstance(t.children[1], icon)
+    assert t.children[1].name == "chevron-right"
+
+    assert len(t.selected_items) == 0
+
+
+def test_selected_and_expanded():
+    key = None
+    one_key = None
+    two_key = None
+    three_key = None
+    selected = None
+    two_was_expanded = False
+    two_was_collapsed = False
+
+    def my_app():
+        nonlocal key, one_key, two_key, three_key, selected, two_was_expanded, two_was_collapsed
+
+        with tree(selection="multiple") as t:
+            one = tree_item("One")
+            with tree_item("Two") as two:
+                three = tree_item("Three")
+
+        key = t._key
+        one_key = one._key
+        two_key = two._key
+        three_key = three._key
+
+        selected = [item._key for item in t.selected_items]
+
+        two_was_expanded = two.was_expanded
+        two_was_collapsed = two.was_collapsed
+
+    with MockRunner(my_app) as mr:
+        assert selected == []
+
+        mr.process_updates([(key, "_selected_keys", [one_key])])
+
+        assert selected == [one_key]
+
+        mr.process_updates([(key, "_selected_keys", [one_key, two_key, three_key])])
+
+        assert selected == [one_key, two_key, three_key]
+
+        mr.process_updates([(two_key, "expanded", True), (two_key, "changed", True)])
+
+        assert two_was_expanded
+        assert not two_was_collapsed
+
+        mr.process_updates([(two_key, "expanded", False), (two_key, "changed", True)])
+
+        assert not two_was_expanded
+        assert two_was_collapsed

hyperdiv/components/text.py

@@ -0,0 +1,112 @@
+from ..prop import Prop
+from ..prop_types import String
+from ..component_base import Component
+from ..component_mixins.styled import Styled
+from .common.text_utils import concat_text
+
+
+class text(Component, Styled):
+    """
+    Renders a block of text.
+
+    ```py
+    hd.text("Hello World")
+    ```
+
+    ### Can be styled
+
+    ```py
+    hd.text(
+        "Hello World",
+        border="1px solid green-200",
+        background_color="green-50",
+        padding=1,
+        border_radius="large",
+        width="fit-content",
+    )
+    ```
+
+    """
+
+    _name = "text"
+    _tag = "p"
+
+    content = Prop(String, "")
+
+    def __init__(self, *content, **kwargs):
+        """
+        The chunks passed in `*content` will be joined by `" "` and used
+        to initialize the `content` prop.
+
+        ```py
+        x = 2
+        hd.text("I have", x, "chickens.")
+        # is equivalent to
+        hd.text(content=f"I have {x} chickens.")
+        ```
+
+        """
+        if content:
+            kwargs["content"] = concat_text(content)
+        super().__init__(**kwargs)
+
+
+class h1(text):
+    """
+    A component that works identically to @component(text) but renders
+    an HTML `<h1>` tag, the largest possible heading.
+
+    This is roughly equivalent to using one hash-mark in Markdown:
+    `hd.markdown("# Heading")`.
+
+    """
+
+    _tag = "h1"
+
+
+class h2(text):
+    """
+    A component that works identically to @component(text) but renders
+    an HTML `<h2>` tag, one step smaller than @component(h1).
+
+    This is roughly equivalent to using two hash-marks in Markdown:
+    `hd.markdown("## Heading")`.
+    """
+
+    _tag = "h2"
+
+
+class h3(text):
+    """
+    A component that works identically to @component(text) but renders
+    an HTML `<h3>` tag, one step smaller than @component(h2).
+
+    This is roughly equivalent to using three hash-marks in Markdown:
+    `hd.markdown("### Heading")`.
+    """
+
+    _tag = "h3"
+
+
+class h4(text):
+    """
+    A component that works identically to @component(text) but renders
+    an HTML `<h4>` tag, one step smaller than @component(h3).
+
+    This is roughly equivalent to using four hash-marks in Markdown:
+    `hd.markdown("#### Heading")`.
+    """
+
+    _tag = "h4"
+
+
+class h5(text):
+    """
+    A component that works identically to @component(text) but renders
+    an HTML `<h5>` tag, one step smaller than @component(h4).
+
+    This is roughly equivalent to using five hash-marks in Markdown:
+    `hd.markdown("##### Heading")`.
+    """
+
+    _tag = "h5"

hyperdiv/components/text_input.py

@@ -0,0 +1,241 @@
+from ..prop_types import String, Bool, Optional, Int, OneOf, BoolEvent
+from ..prop import Prop
+from ..slot import Slot
+from .common.shoelace_types import (
+    ShoelaceSize,
+    InputAutoCapitalize,
+    InputAutoCorrect,
+    InputEnterKeyHint,
+    InputMode,
+)
+from ..style_part import BasePart, StylePart
+from .common.label_component import LabelComponent
+from .common.text_utils import concat_text
+from .icon import icon
+from .text import text
+
+
+class text_input(LabelComponent):
+    """
+    The Hyperdiv text input component.
+
+    ```py
+    ti = hd.text_input(placeholder="Enter some text")
+    hd.text("You entered:", ti.value)
+    ```
+
+    ## Input Types
+
+    `text_input` supports multiple types of inputs, including
+    passwords, numbers, dates, and times.
+
+    ```py
+    hd.text_input(
+        "Enter a number:",
+        input_type="number"
+    )
+    hd.text_input(
+        "Enter a password:",
+        input_type="password",
+        password_toggle=True,
+    )
+    hd.text_input(
+        "Enter a date:",
+        input_type="date"
+    )
+    hd.text_input(
+        "Enter a date and time:",
+        input_type="datetime-local"
+    )
+    hd.text_input(
+        "Enter a time:",
+        input_type="time"
+    )
+    ```
+
+    Some of the props of `text_input` are only relevant for certain
+    input types. For example the `password_toggle` prop, shown above,
+    will only affect the `password` input type.
+
+    ## Slots
+
+    `text_input` supports slots for adding prefix and suffix icons to
+    the input.
+
+    ```py
+    hd.text_input(
+        prefix_icon="gear",
+        suffix_icon="chevron-right"
+    )
+    ```
+
+    The password show/hide icons can also be customized:
+
+    ```py
+    hd.text_input(
+        value="mypassword",
+        input_type="password",
+        password_toggle=True,
+        show_password_icon="sunglasses",
+        hide_password_icon="eyeglasses",
+    )
+    ```
+    """
+
+    _name = "text_input"
+    _tag = "sl-input"
+    _has_direct_children = False
+
+    # The type of the input.
+    #
+    # * `text`: The default type.
+    # * `time`: Renders a time picker in the input.
+    # * `date`: Renders a date picker in the input.
+    # * `datetime-local`: Renders a date and time picker.
+    # * `number`: Restricts the input to a number, and shows a number
+    #   keyboard on mobile.`text_input` exposes additional options
+    #   specific to this input type.
+    # * `password`: Renders a password input, with the input value
+    #   obscured by default. `text_input` exposes additional options
+    #   specific to this input type.
+    # * `tel`: Functionally identical to `text` but may render a
+    #   keyboard specific for inputting phone numbers while on mobile.
+    # * `search`: Functionally identical to `text` but may be styled
+    #   specifically by the browser.
+    input_type = Prop(
+        OneOf(
+            "date",
+            "datetime-local",
+            # "email",
+            "number",
+            "password",
+            "search",
+            "tel",
+            "text",
+            "time",
+            # "url",
+        ),
+        "text",
+        ui_name="type",
+    )
+    # The name of the text input. If left unspecified, it is set to
+    # the label.
+    name = Prop(String, "")
+    # The value/contents of the text input.
+    value = Prop(String, "")
+    # The size of the text input.
+    size = Prop(ShoelaceSize, "medium")
+    # Whether the text input should be rendered with a filled style.
+    filled = Prop(Bool, False)
+    # Whether the text input should be rendered as a pill.
+    pill = Prop(Bool, False)
+    # Help text/hint to be rendered under the input.
+    help_text = Prop(String, "")
+    # Whether a "x" button should be rendered that clears the input
+    # when clicked.
+    clearable = Prop(Bool, False)
+    # Whether the text input should be rendered as disabled.
+    disabled = Prop(Bool, False)
+    # A placeholder to show when the input is empty. This prop will
+    # not render anything for date and time inputs, which are
+    # pre-populated with a date/time picker.
+    placeholder = Prop(String, "")
+    # Whether the input is readonly.
+    readonly = Prop(Bool, False)
+    # If the input type is `"password"`, whether to render a button
+    # that allows revealing the password.
+    password_toggle = Prop(Bool, False)
+    # Whether the password is visible.
+    password_visible = Prop(Bool, False)
+    # When the input type is `number`, this option hides the
+    # increment/decrement buttons.
+    no_spin_buttons = Prop(Bool, False)
+    # The minimum length of the input, in number of characters.
+    minlength = Prop(Optional(Int))
+    # The maximum length of the input, in number of characters.
+    maxlength = Prop(Optional(Int))
+    # If the input type is `"number"` this sets the minimum value that
+    # can be typed in.
+    min_value = Prop(Optional(Int), ui_name="min")
+    # If the input type is `"number"`, this sets the maximum value that
+    # can be typed in.
+    max_value = Prop(Optional(Int), ui_name="max")
+    # If the input type is `"number"`, this determines the
+    # step/increment that the value increments/decrements by when
+    # clicking the up/down buttons.
+    step = Prop(Optional(Int))
+    # Determines how input text will be auto-capitalized.
+    autocapitalize = Prop(InputAutoCapitalize)
+    # Determines how input text will be auto-corrected.
+    autocorrect = Prop(InputAutoCorrect)
+    autocomplete = Prop(Optional(String))
+    # Whether this text input should be auto-focused.
+    autofocus = Prop(Optional(Bool))
+    # Determines the behavior of the Enter key.
+    enterkeyhint = Prop(InputEnterKeyHint)
+    # Whether spell-check is turned on.
+    spellcheck = Prop(Bool, False)
+    # Determines the virtual keyboard shown on mobile.
+    inputmode = Prop(InputMode)
+    # A regex pattern that restricts what can be typed in this input.
+    pattern = Prop(Optional(String))
+    # Whether the input value changed in this run.
+    changed = Prop(BoolEvent, False)
+
+    label_slot = Slot(ui_name="label")
+    prefix = Slot()
+    suffix = Slot()
+    clear = Slot(ui_name="clear-icon")
+    show_password = Slot(ui_name="show-password-icon")
+    hide_password = Slot(ui_name="hide-password-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"))
+    input_base_style = Prop(StylePart("base"))
+    input_style = Prop(StylePart("input"))
+    prefix_style = Prop(StylePart("prefix"))
+    clear_button_style = Prop(StylePart("clear-button"))
+    password_toggle_button_style = Prop(StylePart("password-toggle-button"))
+    suffix_style = Prop(StylePart("suffix"))
+
+    def __init__(
+        self,
+        *label,
+        name=None,
+        prefix_icon=None,
+        suffix_icon=None,
+        clear_icon=None,
+        show_password_icon=None,
+        hide_password_icon=None,
+        **kwargs,
+    ):
+        """
+        The `*label` argument sets the text input's label.
+
+        The kwargs suffixed by `_icon` each take an icon name and slot
+        that icon into the respective slot.
+        """
+        if name is None:
+            name = concat_text(label)
+
+        super().__init__(*label, name=name, **kwargs)
+
+        with self:
+            if prefix_icon:
+                icon(prefix_icon, slot=self.prefix)
+            if suffix_icon:
+                icon(suffix_icon, slot=self.suffix)
+            if clear_icon:
+                icon(clear_icon, slot=self.clear)
+            if show_password_icon:
+                icon(show_password_icon, slot=self.show_password)
+            if hide_password_icon:
+                icon(hide_password_icon, slot=self.hide_password)
+
+    def reset(self):
+        self.reset_prop("value")
+
+    def _get_label_slot(self):
+        return self.label_slot

hyperdiv/components/textarea.py

@@ -0,0 +1,68 @@
+from ..prop_types import String, Bool, OneOf, Int, Optional, BoolEvent
+from ..prop import Prop
+from ..slot import Slot
+from .common.shoelace_types import (
+    ShoelaceSize,
+    InputAutoCapitalize,
+    InputAutoCorrect,
+    InputEnterKeyHint,
+    InputMode,
+)
+from ..style_part import BasePart, StylePart
+from .common.label_component import LabelComponent
+from .common.text_utils import concat_text
+
+
+class textarea(LabelComponent):
+    """
+    A text area component.
+
+    ```py
+    hd.textarea(placeholder="Type here")
+    ```
+    """
+
+    _name = "textarea"
+    _tag = "sl-textarea"
+
+    value = Prop(String, "")
+    name = Prop(String, "")
+    size = Prop(ShoelaceSize, "medium")
+    filled = Prop(Bool, False)
+    help_text = Prop(String, "")
+    placeholder = Prop(String, "")
+    rows = Prop(Int, 4)
+    resize = Prop(OneOf("none", "vertical", "auto"), "vertical")
+    disabled = Prop(Bool, False)
+    readonly = Prop(Bool, False)
+    minlength = Prop(Optional(Int))
+    maxlength = Prop(Optional(Int))
+    autocapitalize = Prop(InputAutoCapitalize)
+    autocorrect = Prop(InputAutoCorrect)
+    autocomplete = Prop(Optional(String))
+    autofocus = Prop(Bool, False)
+    enterkeyhint = Prop(InputEnterKeyHint)
+    spellcheck = Prop(Bool, False)
+    inputmode = Prop(InputMode)
+    changed = Prop(BoolEvent, False)
+
+    label_slot = Slot(ui_name="label")
+
+    base_style = Prop(BasePart("form-control"))
+    input_wrapper_style = Prop(StylePart("form-control-input"))
+    input_base_style = Prop(StylePart("base"))
+    input_style = Prop(StylePart("textarea"))
+    label_style = Prop(StylePart("form-control-label"))
+    help_text_style = Prop(StylePart("form-control-help-text"))
+
+    def __init__(self, *label, name=None, **kwargs):
+        if name is None:
+            name = concat_text(label)
+
+        super().__init__(*label, name=name, **kwargs)
+
+    def reset(self):
+        self.reset_prop("value")
+
+    def _get_label_slot(self):
+        return self.label_slot

hyperdiv/components/theme.py

@@ -0,0 +1,75 @@
+from ..prop_types import OneOf, BoolEvent
+from ..prop import Prop
+from ..ui_singleton import BrowserSingleton
+from .local_storage import local_storage
+
+
+class theme(BrowserSingleton):
+    """
+    Allows access to the light/dark mode theme setting. You can set
+    the theme by mutating the `mode` prop.
+
+    ```py
+    theme = hd.theme()
+    icon = "sun"
+    mode = "light"
+    if theme.is_light:
+        icon = "moon"
+        mode = "dark"
+    if hd.icon_button(icon).clicked:
+        theme.mode = mode
+    ```
+    """
+
+    _name = "theme"
+    _key = "theme"
+
+    # The current system theme setting. This prop is automatically,
+    # internally-updated as the system setting changes. Even though
+    # this prop technically accepts `None` as a value, `None` is never
+    # visible from a user perspective. It is set to `None` only
+    # briefly on startup, and is immediately updated to a concrete
+    # value before the application runs.
+    system_mode = Prop(OneOf(None, "light", "dark"), backend_immutable=True)
+    # The theme mode. If the mode is set to `"system"`, the theme
+    # follows the value of the `system_mode` prop.
+    mode = Prop(OneOf(None, "system", "light", "dark"))
+    # True for one run when one of the theme props changed.
+    changed = Prop(BoolEvent, False)
+
+    def __init__(self):
+        super().__init__()
+
+    @property
+    def is_light(self):
+        """
+        Returns `True` if the theme is in light mode, and `False` if the
+        theme is in dark mode, regardless of whether the theme mode is
+        set by the user or follows system.
+        """
+        if self.mode == "system":
+            return self.system_mode == "light"
+        else:
+            return self.mode == "light"
+
+    @property
+    def is_dark(self):
+        """The inverse of `is_light`."""
+        return not self.is_light
+
+    def set_and_remember_theme_mode(self, mode):
+        """
+        Sets the theme mode and updates the browser's local storage to
+        remember this setting. Upon app revisits/reloads, the theme
+        will load with this setting.
+        """
+        self.mode = mode
+        local_storage.set_item("$hyperdiv.theme_mode", mode)
+
+    def reset_and_forget_theme_mode(self):
+        """
+        Removes the theme mode setting from the browser's local storage,
+        causing the theme setting to default to `system`.
+        """
+        self.mode = "system"
+        local_storage.remove_item("$hyperdiv.theme_mode")