hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/components/image.py

@@ -0,0 +1,86 @@
+import base64
+from ..prop_types import PureString, HyperdivType
+from ..prop import Prop
+from ..component_base import Component
+from ..component_mixins.interactive import Interactive
+from ..component_mixins.styled import Styled
+
+
+class ImageSrcDef(HyperdivType):
+    """
+    The type of an @component(image) `src` prop.
+
+    It accepts the following value shapes:
+
+    (a) A string that is either a (local or remote) path to an
+    image. This is the most common case. For example
+    `"/assets/my-image.jpg"` or `"https://url.com/path/to/image.png"`.
+
+    (b) A string that contains browser-ready base64-encoded image
+    bytes. The string must take this shape, otherwise the browser will
+    not be able to render it:
+
+    ```sh
+    "data:{mime_type};base64,{the_actual_base64_string}"
+    ```
+
+    The `{mime_type}` can generally be left blank, and browsers will
+    auto-infer it. See here for a list of mime types:
+    https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+
+    (c) Raw image bytes. The bytes will automatically be converted to a
+    browser-ready base64 string. The image mime type will be left
+    blank, letting the browser infer it.
+
+    (d) A tuple `(image_bytes, mime_type)`. Same as (c), but allows
+    explicitly adding a mime type. The mime type will be passed on to
+    the browser verbatim.
+
+    Note that if you explicitly set a mime type, browsers will
+    likely ignore it if it doesn't match what the browser inferred
+    from the bytes. In general it's safe to not worry about mime types.
+    """
+
+    def parse(self, value):
+        if isinstance(value, bytes):
+            # Base64 encode the bytes
+            encoded_image_data = base64.b64encode(value).decode("utf-8")
+            value = f"data:;base64,{encoded_image_data}"
+        elif isinstance(value, tuple):
+            image_bytes, mime_type = value
+            if not isinstance(image_bytes, bytes) or not isinstance(mime_type, str):
+                raise ValueError("Bad image src format.")
+            encoded_image_data = base64.b64encode(image_bytes).decode("utf-8")
+            value = f"data:{mime_type};base64,{encoded_image_data}"
+        else:
+            value = PureString.parse(value)
+        return value
+
+
+ImageSrc = ImageSrcDef()
+
+
+class image(Component, Styled, Interactive):
+    """
+    An image component.
+
+    ```py
+    hd.image("/assets/kitten.jpg")
+    ```
+
+    When the image source is a path, it can either refer to a local
+    `/assets` path or a remote URL.
+
+    In addition to paths, the `src` prop can also be base64-encoded
+    image bytes. If you pass raw image bytes into the `image`
+    constructor, they will automatically be converted to base64.
+    """
+
+    _name = "image"
+    _tag = "img"
+
+    # The source path or URL of the image.
+    src = Prop(ImageSrc, "")
+
+    def __init__(self, src, **kwargs):
+        super().__init__(src=src, **kwargs)

hyperdiv/components/image_comparer.py

@@ -0,0 +1,45 @@
+from ..prop_types import CSSField, ClampedFloat, Size
+from ..prop import Prop
+from ..component_base import Component
+from ..slot import Slot
+from ..component_mixins.styled import Styled
+from ..style_part import BasePart, StylePart
+
+
+class image_comparer(Component, Styled):
+    """
+    A component that allows visually comparing two images by sliding a divider.
+
+    ```py
+    with hd.image_comparer() as ic:
+        hd.image(
+            "/assets/kitten-bw.jpg",
+            slot=ic.before
+        )
+        hd.image(
+            "/assets/kitten.jpg",
+            slot=ic.after
+        )
+    ```
+    """
+
+    _name = "image_comparer"
+    _tag = "sl-image-comparer"
+    _has_direct_children = False
+
+    # The divider position, as a percentage.
+    position = Prop(ClampedFloat(0, 100), 50)
+    # The divider width.
+    divider_width = Prop(CSSField("--divider-width", Size))
+    # The size of the divider handle.
+    handle_size = Prop(CSSField("--handle-size", Size))
+
+    before = Slot()
+    after = Slot()
+    handle = Slot()
+
+    base_style = Prop(BasePart())
+    before_style = Prop(StylePart("before"))
+    after_style = Prop(StylePart("after"))
+    divider_style = Prop(StylePart("divider"))
+    handle_style = Prop(StylePart("handle"))

hyperdiv/components/lifecycle.py

@@ -0,0 +1,47 @@
+from ..prop import Prop
+from ..prop_types import BoolEvent
+from ..ui_singleton import Singleton
+
+
+class lifecycle(Singleton):
+    """
+    The `lifecycle` component gives you the opportunity to execute
+    one-time actions when the app starts or stops.
+
+    For example you can allocate resources on app start, and
+    de-allocate them before the app exits.
+
+    Or if you have long-running @component(task)s you can signal those
+    tasks to exit. The app won't cleanly shut down if there are
+    lingering tasks still executing.
+
+    ```py-nodemo
+
+    def my_task(state):
+        state.running = True
+
+        while state.running:
+            do_something()
+
+    def app():
+        state = hd.state(running=False)
+
+        task = hd.task()
+        task.run(my_task, state)
+
+        lifecycle = hd.lifecycle()
+        if lifecycle.app_stopped:
+            state.running = False
+    ```
+
+    Note that if the app function crashes, the code that is supposed
+    to execute on `app_stopped` may not be executed.
+    """
+
+    _key = "lifecycle"
+
+    # True for one frame when the app function runs for the first
+    # time.
+    app_started = Prop(BoolEvent, False)
+    # True for one frame when the app function runs for the last time.
+    app_stopped = Prop(BoolEvent, False)

hyperdiv/components/link.py

@@ -0,0 +1,89 @@
+from ..prop_types import CSS, Bool, PureString, OneOf
+from ..prop import Prop
+from ..component_mixins.interactive import Interactive
+from .common.text_utils import concat_text
+from .plaintext import plaintext
+from .box import box
+
+
+class LinkUnderlineDef(CSS):
+    """
+    A `Bool` type, accepting the values `True` and `False`,
+    determining whether to render an underline on the given
+    component's text.
+    """
+
+    def parse(self, value):
+        return Bool.parse(value)
+
+    def render(self, value):
+        return {"text-decoration": "underline" if value else "none"}
+
+    def __repr__(self):
+        return "LinkUnderline"
+
+
+LinkUnderline = LinkUnderlineDef()
+
+
+class link(box, Interactive):
+    """
+    A HTML link.
+
+    ```py
+    hd.link(
+        "Link to a remote website",
+        href="https://google.com"
+    )
+    hd.link(
+        "Link to a local path",
+        href="/reference/components",
+    )
+    ```
+
+    `link` inherits from @component(box), so it can be styled like a
+    `box` and arbitrary components can be placed inside it.
+
+    For accessibility, the link's body should be kept simple, and you
+    should avoid nesting interactive components like buttons inside a
+    link.
+
+    ```py
+    with hd.link(
+        href="https://google.com",
+        direction="horizontal",
+        padding=1,
+        gap=0.5,
+        border="1px solid green",
+        hover_background_color="green-50",
+        border_radius="large",
+        width="fit-content",
+        align="center"
+    ):
+        hd.icon("google")
+        hd.text("A fancy link")
+    ```
+
+    """
+
+    _name = "link"
+    _tag = "a"
+
+    # The path or URL to navigate to when clicking the link.
+    href = Prop(PureString)
+    # Whether a classic underline should be rendered on the link text.
+    underline = Prop(LinkUnderline, False)
+    # Determines where the link is opened. See the [W3Schools target
+    # documentation](https://www.w3schools.com/tags/att_a_target.asp)
+    target = Prop(OneOf(None, "_blank", "_parent", "_self", "_top"), "_blank")
+    # See `rel` docs [here](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel).
+    rel = Prop(PureString, "noreferrer noopener")
+
+    def __init__(self, *label, cursor="pointer", font_color="blue", **kwargs):
+        label = concat_text(label)
+
+        super().__init__(cursor=cursor, font_color=font_color, **kwargs)
+
+        if label:
+            with self:
+                plaintext(label)

hyperdiv/components/list.py

@@ -0,0 +1,47 @@
+from ..prop_types import CSSField, OneOf
+from ..prop import Prop
+from .common.list_base import list_base
+
+
+class list(list_base):
+    """
+    Renders an unordered (bullet-point) list of @component(list_item)s.
+
+    ```py
+    hd.text("Here is a list:")
+    with hd.list():
+        hd.list_item("One")
+        hd.list_item("Two")
+        hd.list_item("Three")
+        hd.list_item("Four")
+    ```
+
+    ### Custom item numbers
+
+    The bullet formatting can be controlled via the `style_type` prop.
+
+    ```py
+    hd.text("Here is a list:")
+    with hd.list(style_type="square"):
+        hd.list_item("One")
+        hd.list_item("Two")
+        hd.list_item("Three")
+        hd.list_item("Four")
+    ```
+    """
+
+    _name = "list"
+    _tag = "ul"
+
+    style_type = Prop(
+        CSSField(
+            "list-style-type",
+            OneOf(
+                "none",
+                "circle",
+                "square",
+                "disc",
+            ),
+        ),
+        "disc",
+    )

hyperdiv/components/list_item.py

@@ -0,0 +1,11 @@
+from .common.label_component import LabelComponent
+
+
+class list_item(LabelComponent):
+    """
+    A list item component to be used with @component(list) or @component(ordered_list).
+    Not useful on its own.
+    """
+
+    _name = "list_item"
+    _tag = "li"

hyperdiv/components/local_storage.py

@@ -0,0 +1,123 @@
+from ..ui_command import UICommandCache, ui_read, ui_write
+
+
+class local_storage:
+    """
+    A Hyperdiv interface to browser localStorage. Using this interface,
+    you can read and write data into the user's browser, and this data
+    persists across app visits. `local_storage` can be used to
+    implement authentication and store various user settings.
+
+    See also: @component(cookies).
+
+    Each `local_storage` function returns an @component(async_command)
+    component. The `async_command` can be used to inspect whether the
+    function is still running, and its return value if it is done
+    running.
+
+    `local_storage` maintains an internal cache of
+    @component(async_command) objects that have been returned by reads
+    (`get_item` and `has_item`). The cache is keyed by the local
+    storage key. When a write (`set_item`, `remove_item`) is invoked
+    at that key, the related `async_command` objects will be reset. This
+    will trigger corresponding reads to re-run and get the new values.
+
+    When `clear()` is called, all keys are removed from localStorage
+    and the cache, and all reads re-run.
+
+    ```py
+    command = hd.local_storage.get_item("test_key")
+
+    hd.markdown("`test_key` value:", command.result)
+
+    if hd.button("Set key").clicked:
+        hd.local_storage.set_item("test_key", "Bunnies")
+
+    if hd.button("Remove key").clicked:
+        hd.local_storage.remove_item("test_key")
+    ```
+
+    """
+
+    # A cache that remembers results from previous local storage reads
+    # (`get_item` and `has_item` calls). When a write is invoked on a
+    # key that has been read before, those results are cleared,
+    # triggering a re-read.
+
+    _cache = UICommandCache("local_storage_result_cache")
+
+    def __init__(self):
+        """
+        Unlike typical Hyperdiv components, `local_storage` cannot be
+        instantiated. All methods are static.
+        """
+        raise Exception("local_storage cannot be instantiated.")
+
+    #
+    # Local storage reads.
+    #
+
+    @staticmethod
+    def get_item(key):
+        """
+        Calls the browser's `window.localStorage.getItem(key)`.
+        """
+        result, sent = ui_read("localStorage", "getItem", [key])
+        if sent:
+            local_storage._cache.cache_result(key, result)
+        return result
+
+    @staticmethod
+    def has_item(key):
+        """
+        Tests if a key exists in the browser's localStorage. The returned
+        @component(async_command)'s `result` prop is set to `True` if the
+        given key exists in the browser's localStorage, or `False`
+        otherwise.
+        """
+        result, sent = ui_read("localStorage", "hasItem", [key])
+        if sent:
+            local_storage._cache.cache_result(key, result)
+        return result
+
+    #
+    # Local storage writes.
+    #
+
+    @staticmethod
+    def set_item(key, value):
+        """
+        Calls the browser's `window.localStorage.setItem(key, value)`.
+        """
+
+        if not isinstance(value, str):
+            raise ValueError("local_storage.set_item can only store strings.")
+
+        result = ui_write("localStorage", "setItem", [key, value])
+
+        local_storage._cache.clear_cache_at_key(key)
+
+        return result
+
+    @staticmethod
+    def remove_item(key):
+        """
+        Calls the browser's `window.localStorage.removeItem(key)`.
+        """
+        result = ui_write("localStorage", "removeItem", [key])
+
+        local_storage._cache.clear_cache_at_key(key)
+
+        return result
+
+    @staticmethod
+    def clear():
+        """
+        Calls the browser's `window.localStorage.clear()`, removing all the
+        keys from localStorage.
+        """
+        result = ui_write("localStorage", "clear", [])
+
+        local_storage._cache.clear_cache()
+
+        return result

hyperdiv/components/location.py

@@ -0,0 +1,132 @@
+from ..prop_types import HyperdivType, PureString, String, Optional
+from ..prop import Prop
+from ..ui_singleton import BrowserSingleton
+
+
+def check_forbidden_delimiters(value):
+    if "#" in value:
+        raise ValueError("'#' cannot occur in a path")
+    if "?" in value:
+        raise ValueError("'?' cannot occur in a path")
+
+
+class LocationPartDef(HyperdivType):
+    """
+    This type is used by @component(location) to express location
+    parts. It takes a string but it rejects strings containing the
+    characters `"?"` or `"#"`.
+    """
+
+    def parse(self, value):
+        path = String.parse(value)
+        check_forbidden_delimiters(path)
+        return value
+
+    def render(self, path):
+        return String.render(path)
+
+    def __repr__(self):
+        return "LocationPart"
+
+
+LocationPart = LocationPartDef()
+
+
+class PathStringDef(LocationPartDef):
+    """
+    This type is used by @component(location) to express the location path.
+    It takes a string but:
+
+    * It rejects path strings containing the characters `"?"` or `"#"`.
+    * If the path string is "/", it leaves it as is.
+    * If the path string is empty, it sets it to "/".
+    * If the path ends in "/", it strips the trailing "/". So
+      "/foo/bar/" is set to "/foo/bar"
+    """
+
+    def parse(self, value):
+        path = super().parse(value)
+        if path == "":
+            path = "/"
+        if path != "/":
+            path = path.rstrip("/")
+        return path
+
+    def __repr__(self):
+        return "PathString"
+
+
+PathString = PathStringDef()
+
+
+class location(BrowserSingleton):
+    """
+    `location` is a Hyperdiv component that gives access to the
+    browser's location bar.  Using `location`, you can render
+    different things for different location paths, query args, and
+    hash args.
+
+    `location` offers three props: `path`, `query_args`, and `hash_arg`.
+
+    If the browser location is `https://my-app.com/foo/bar?a=1&b=2#hello`, then:
+
+    * `location().protocol == "https:"`
+    * `location().host == "my-app.com"`
+    * `location().path == "/foo/bar"`
+    * `location().query_args == "a=1&b=2"`
+    * `location().hash_arg == "hello"`
+
+    You can change the location by using the `go()` method. For
+    example, to change the location to `"/foo/bar"`, you can call
+    `location().go(path="/foo/bar")`.
+
+    Changing the location by using `go()` or mutating the location
+    props is useful in some cases, but in general is an anti-pattern
+    and you should instead use @component(link)s to implement
+    navigation.
+    """
+
+    _name = "location"
+    _key = "location"
+
+    # The protocol part of the browser location bar.
+    protocol = Prop(Optional(PureString), backend_immutable=True)
+    # The host part of the browser location bar.
+    host = Prop(Optional(PureString), backend_immutable=True)
+    # The path part of the browser location bar.
+    path = Prop(Optional(PathString))
+    # The query args part of the browser location bar, not including
+    # the leading `?`.
+    query_args = Prop(Optional(LocationPart))
+    # The hash part of the location bar, not including the leading
+    # `#`.
+    hash_arg = Prop(Optional(LocationPart))
+
+    def go(self, path, query_args="", hash_arg=""):
+        """
+        Change the browser location bar by simultaneously mutating all
+        three props. For example, `go(path="/foo", hash_arg="bar")` will
+        set the location to `"/foo#bar"`. If `query_args` is currently
+        set to a value, if will be set to `""`.
+
+        If you need to programmatically mutate the location, this is
+        the recommended way to do it. If instead you mutate
+        individual props, say `location().path = "/foo"`, that will
+        only change the path prop, and let the other props remain
+        unchanged, which is probably not what you want.
+        """
+        self.path = path
+        self.query_args = query_args
+        self.hash_arg = hash_arg
+
+    def to_string(self):
+        """
+        Returns a string of the full location, suitable for pasting into
+        the browser's location bar.
+        """
+        string = f"{self.protocol}//{self.host}{self.path}"
+        if self.query_args:
+            string += f"?{self.query_args}"
+        if self.hash_arg:
+            string += f"#{self.hash_arg}"
+        return string