hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/component_base.py

@@ -0,0 +1,329 @@
+import asyncio
+from functools import cache
+from .prop import Prop
+from .frame import AppRunnerFrame, StateAccessFrame, TaskFrame
+from .renderer import render_component
+from .slot import Slot
+from .collector import Collector
+from .component_keys import (
+    get_component_key,
+    validate_component_key,
+    register_component_key,
+)
+from .component_mixins.slottable import Slottable
+from .prop_types import Event
+
+
+class Component(Collector):
+    """
+    The base class for all Hyperdiv components.
+
+    Should not be instantiated directly.
+    """
+
+    def __init__(self, *, key=None, collect=True, **prop_kwargs):
+        super().__init__()
+
+        frame = StateAccessFrame.current()
+        frame.component_count += 1
+
+        fixed_key = getattr(type(self), "_key", None)
+
+        # Tasks are not allowed to create components, but they're
+        # allowed to access global states.
+        if not (key or fixed_key or isinstance(frame, AppRunnerFrame)):
+            if isinstance(frame, TaskFrame):
+                raise Exception("Cannot create UI components in a task.")
+            else:
+                raise Exception("Cannot create UI components in this context.")
+
+        if key is not None:
+            if not validate_component_key(key):
+                raise ValueError(
+                    f"Invalid key: {key}. Keys should be strings that start with a letter "
+                    'and may contain letters, numbers, and the characters "-" and "_".'
+                )
+            self._key = get_component_key(key=key)
+            register_component_key(self._key)
+        elif fixed_key:
+            # We do not register fixed keys / do not check for
+            # duplicates in fixed keys.
+            self._key = fixed_key
+            fixed_key = True
+        else:
+            self._key = get_component_key()
+            register_component_key(self._key)
+
+        # Hyperdiv internal component name -- normally derived from the class name
+        self._name = getattr(type(self), "_name", None) or type(self).__name__
+        # The component's HTML tag as rendered in the UI
+        self._tag = getattr(type(self), "_tag", None)
+        # The component's HTML classes
+        self._classes = getattr(type(self), "_classes", [])
+        # The component's props, a list of Prop objects
+        self._props = self._get_props()
+        # The component's slots, a list of Slot objects
+        self._slots = self._get_slots()
+        # Whether the component can contain "direct" children, meaning
+        # other than slotted children. Some components may allow
+        # children but only in slots.
+        self._has_direct_children = getattr(type(self), "_has_direct_children", True)
+        # Whether the component can accept children, direct or in slots
+        self._has_children = self._has_direct_children or len(self._slots) > 0
+        # Whether the component can accept any more children. A
+        # component can accept some children, then become sealed, in
+        # which case it raises an exception if you try to add more
+        # children to it.
+        self._sealed = False
+        # Whether the component has been collected. The component can
+        # only be collected once per frame.
+        self._collected = False
+
+        self._init_props(**prop_kwargs)
+        if collect:
+            self.collect()
+
+    def collect(self):
+        """
+        Called when the component is collected into the dom. If the
+        component was constructed with `collect=False`, this method has
+        to be called by the user code. Otherwise it is called
+        automatically when the component is constructed.
+        """
+        if self._collected:
+            raise ValueError("The component has already been collected.")
+        AppRunnerFrame.current().collector_stack.collect(self)
+        self._collected = True
+
+    def _collect_child(self, child):
+        if isinstance(child, Slottable) and child.slot:
+            if child.slot not in self._slots:
+                raise Exception(
+                    f'Slot "{child.slot.name}" is invalid on this component.'
+                )
+        elif not self._has_direct_children:
+            raise Exception("Cannot collect non-slotted elements into this component.")
+
+        super()._collect_child(child)
+
+    def __enter__(self):
+        if self._has_children and not self._sealed:
+            AppRunnerFrame.current().collector_stack.push(self)
+            return self
+        raise Exception(f"'{self._name}' cannot have children.")
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        AppRunnerFrame.current().collector_stack.pop()
+
+    @property
+    def children(self):
+        """
+        Returns the list of children of this component, if this
+        component can have children. If the component cannot have
+        children, accessing this property raises `ValueError`.
+        """
+
+        if self._has_children:
+            return self._children
+        raise ValueError(f"'{self._name}' cannot have children.")
+
+    def render(self):
+        """
+        Returns the rendered component in the internal Hyperdiv JSON
+        format. This function is used internally, but may be useful
+        for debugging.
+        """
+        return render_component(self)
+
+    def _get_props(self):
+        return type(self)._get_static_props()
+
+    def _get_slots(self):
+        return type(self)._get_static_slots()
+
+    @classmethod
+    @cache
+    def _get_static_props(cls):
+        unique_props = dict()
+        for klass in reversed(cls.__mro__[:-1]):
+            unique_props.update(
+                {
+                    attr.name: attr
+                    for attr in klass.__dict__.values()
+                    if isinstance(attr, Prop)
+                }
+            )
+
+        props = unique_props.values()
+        camlcase_props = getattr(cls, "_camlcase_props", True)
+        if not camlcase_props:
+            for prop in props:
+                prop.camlcase_ui_name = False
+        return props
+
+    @classmethod
+    @cache
+    def _get_static_slots(cls):
+        slots = dict()
+        for klass in reversed(cls.__mro__[:-1]):
+            slots.update(
+                {
+                    attr.name: attr
+                    for attr in klass.__dict__.values()
+                    if isinstance(attr, Slot)
+                }
+            )
+        return slots.values()
+
+    def _get_stored_props(self):
+        return StateAccessFrame.current().get_props(self._key)
+
+    def _get_stored_prop(self, prop_name):
+        return self._get_stored_props().get(prop_name)
+
+    def trigger_event(self, prop_name, value):
+        """
+        Triggers the event prop with name `prop_name` by setting its value
+        to `value`.
+        """
+        StateAccessFrame.current().trigger_event(self._key, prop_name, value)
+
+    sentinel = object()
+
+    def _init_props(self, **prop_kwargs):
+        props_with_values = []
+
+        for prop in self._props:
+            value = prop.default_value
+            new_value = prop_kwargs.pop(prop.name, Component.sentinel)
+            if new_value != Component.sentinel:
+                if isinstance(prop.prop_type, Event):
+                    raise Exception(
+                        f"Cannot initialize the event prop '{prop.name}' "
+                        f"on component '{self._name}'"
+                    )
+                value = new_value
+            props_with_values.append((prop, value))
+
+        if len(prop_kwargs) > 0:
+            raise Exception(
+                f"Invalid keyword arguments on {self._name}: "
+                f"{', '.join(prop_kwargs.keys())}"
+            )
+
+        StateAccessFrame.current().init_props(self._key, props_with_values)
+
+    def set_prop_delayed(self, prop_name, prop_value, delay=1):
+        """
+        Sets the prop with `prop_name` to the value `prop_value` after a
+        delay of `delay` seconds.
+
+        This may be useful for auto-closing an ephemeral alert, dropdown,
+        or dialog, after being shown for some duration of time.
+        """
+        from .components.task import run_asynchronously
+
+        async def set_delayed():
+            await asyncio.sleep(delay)
+            setattr(self, prop_name, prop_value)
+
+        def cb(result=None, error=None):
+            pass
+
+        run_asynchronously(cb, set_delayed)
+
+    def reset_prop(self, prop_name):
+        """
+        Resets the prop with the given name to initial values, as if it were
+        never mutated.
+        """
+        StateAccessFrame.current().reset_state(self._key, prop_name)
+
+    def reset_prop_delayed(self, prop_name, delay=1):
+        """
+        Like `set_prop_delayed` but instead of mutating the prop it resets
+        it to its initial value.
+        """
+        from .components.task import run_asynchronously
+
+        async def reset_delayed():
+            await asyncio.sleep(delay)
+            self.reset_prop(prop_name)
+
+        def cb(result=None, error=None):
+            pass
+
+        run_asynchronously(cb, reset_delayed)
+
+    def reset_component(self):
+        """
+        Reset all component props.
+        """
+        props = self._get_stored_props()
+        frame = StateAccessFrame.current()
+
+        with frame.state_lock:
+            for prop in props.values():
+                if not prop.is_event_prop:
+                    frame.reset_state(self._key, prop.name)
+
+    def reset_component_delayed(self, delay=1):
+        """
+        Like `reset_prop_delayed` but resets all component props.
+        """
+
+        from .components.task import run_asynchronously
+
+        async def reset_delayed():
+            await asyncio.sleep(delay)
+            self.reset_component()
+
+        def cb(result=None, error=None):
+            pass
+
+        run_asynchronously(cb, reset_delayed)
+
+
+class BaseState(Component):
+    """
+    The base class for all non-UI components -- components that never
+    get collected and sent to the browser.
+
+    You can subclass this class to define your own custom state with
+    typed props. You can initialize props by passing corresponding
+    kwargs to your subclass constructor:
+
+    ```py
+    class MyState(hd.BaseState):
+        count = hd.Prop(hd.Int, 0)
+
+        def increment(self):
+            self.count += 1
+
+    # Then, in the app function:
+    state = MyState(count=5)
+    if hd.button("Increment").clicked:
+        state.increment()
+
+    hd.text(state.count)
+    ```
+
+    You can wrap your subclass in @component(global_state) to make the
+    state global, so that all instances share the same underlying state.
+
+    This class is useless if instantiated directly. You should only
+    subclass it.
+    """
+
+    def __init__(self, key=None, **prop_kwargs):
+        """
+        This class should not be instantiated directly.
+        """
+        super().__init__(key=key, collect=False, **prop_kwargs)
+
+    def collect(self):
+        """
+        This method is overridden to do nothing, since state components
+        are not collected into the dom.
+        """
+        pass

hyperdiv/component_keys.py

@@ -0,0 +1,61 @@
+import os
+import inspect
+import xxhash
+from .frame import AppRunnerFrame
+
+runtime_py_path = os.path.join(
+    os.path.dirname(os.path.abspath(__file__)), "app_runner.py"
+)
+
+
+def validate_component_key(key):
+    key = str(key)
+    if len(key) == 0 or not key[0].isalpha():
+        return False
+    for char in key:
+        if not char.isalnum() and char not in ("-", "_"):
+            return False
+    return True
+
+
+def register_component_key(key):
+    hyperdiv_frame = AppRunnerFrame.current()
+    if key in hyperdiv_frame.keys:
+        raise Exception("Duplicate key, perhaps missing scope()")
+    hyperdiv_frame.keys.add(key)
+
+
+def get_component_key(key=None):
+    """Generate a unique component key from the filenames and line numbers
+    of the pertinent functions currently on the stack. It tries to
+    limit the search to user-defined code and avoid traversing the
+    whole stack.
+    """
+
+    # Assumes `get_component_key` is called from a hyperdiv component
+    # definition. `f_back.f_back` then skips (a) the call to this
+    # function and (b) the call to the hyperdiv component, starting
+    # the search at the point the user code called the hyperdiv
+    # component.
+    hyperdiv_frame = AppRunnerFrame.current()
+
+    if not key:
+        stack_frame = inspect.currentframe().f_back.f_back
+        key = ""
+        while stack_frame:
+            filename = stack_frame.f_code.co_filename
+            lineno = stack_frame.f_lineno
+            funcname = stack_frame.f_code.co_name
+            # It stops when it encounters `run_loop`, which the function
+            # from which the user's app function is called.
+            if filename == runtime_py_path and funcname == "run_user_app":
+                break
+            key += f"::{filename}:{lineno}:{funcname}"
+            stack_frame = stack_frame.f_back
+
+        key = str(hyperdiv_frame.scope_stack) + key
+        # Prepend `a` because these keys are used as DOM IDs and a DOM ID
+        # with a leading number is not valid.
+        key = "a" + xxhash.xxh32(key).hexdigest()
+
+    return key

hyperdiv/component_mixins/__init__.py

@@ -0,0 +1,5 @@
+from .boxy import Boxy
+from .interactive import Interactive
+from .styled import Styled
+from .slottable import Slottable
+from .togglable import Togglable

hyperdiv/component_mixins/boxy.py

@@ -0,0 +1,170 @@
+from ..prop_types import Bool, CSSField, OneOf, Optional, Size
+from ..prop import Prop
+
+
+class DirectionDef(CSSField):
+    """
+    Represents the layout direction of @component(box) components.
+    """
+
+    def __init__(self):
+        super().__init__(
+            "flex-direction",
+            OneOf(
+                None, "horizontal", "vertical", "horizontal-reverse", "vertical-reverse"
+            ),
+        )
+
+    def render(self, value):
+        if value is None:
+            return None
+
+        css_value = None
+        if value == "vertical":
+            css_value = "column"
+        elif value == "horizontal":
+            css_value = "row"
+        elif value == "vertical-reverse":
+            css_value = "column-reverse"
+        elif value == "horizontal-reverse":
+            css_value = "row-reverse"
+
+        return {"flex-direction": css_value}
+
+    def __repr__(self):
+        return "Direction"
+
+
+class ScrollDef(Optional):
+    """
+    Defines whether the content inside a component can scroll within
+    the component's "box". The accepted values are:
+
+    * `None` - Unspecified/default behavior.
+
+    * `True` - The component's contents will scroll when they overflow
+      the component's dimensions.
+
+    * `False` - The component's contents will not scroll.
+
+    """
+
+    def __init__(self):
+        super().__init__(Bool)
+
+    def render(self, value):
+        if value is None:
+            return None
+        return "auto" if value else "hidden"
+
+    def __repr__(self):
+        return "Scroll"
+
+
+Scroll = ScrollDef()
+Direction = DirectionDef()
+
+
+class Boxy:
+    """
+    A collection of props for components that are containers. These
+    props control how the children of the component are organized inside
+    the component.
+    """
+
+    """
+    Whether the children of the component are placed side by side
+    (`"horizontal"`) or stacked vertically, with each subsequent
+    component being placed below the previous. In the case of the
+    `-reverse` values, the components are rendered in reverse,
+    starting at the opposite edge:
+
+    ```py
+    hd.markdown("`horizontal`:")
+
+    with hd.box(
+        padding=1,
+        gap=1,
+        direction="horizontal",
+        border="1px solid red"
+    ):
+        hd.button("B1")
+        hd.button("B2")
+
+    hd.markdown("`horizontal-reverse`:")
+
+    with hd.box(
+        padding=1,
+        gap=1,
+        direction="horizontal-reverse",
+        border="1px solid red"
+    ):
+        hd.button("B1")
+        hd.button("B2")
+    ```
+
+    The `-reverse` values are rarely used, but they come in handy in
+    niche cases. For example, when building a chat UI, the component
+    that contains the chat messages may be set to
+    `"vertical-reverse"`. That way, new messages are naturally inserted
+    at the bottom and the component naturally stays scrolled to the
+    bottom as new messages are inserted.
+    """
+    direction = Prop(Direction)
+    # This prop controls how child components are placed *along the
+    # direction* of the component. If the component is `"horizontal"`,
+    # this prop controls the horizontal alignment of the children. If
+    # the component is `"vertical"`, this prop controls the vertical
+    # alignment of the children.
+    align = Prop(
+        CSSField(
+            "align-items",
+            OneOf(
+                None,
+                "start",
+                "center",
+                "end",
+                "stretch",
+            ),
+        )
+    )
+    # This prop complements `direction` and controls how child
+    # components are placed on the axis *opposite to the direction* of
+    # the component. If the component is `"horizontal"`, this prop
+    # controls the *vertical* alignment of the children. If the
+    # component is `"vertical"`, this prop control the *horizontal*
+    # alignment of the children.
+    justify = Prop(
+        CSSField(
+            "justify-content",
+            OneOf(
+                None,
+                "start",
+                "center",
+                "end",
+                "space-between",
+                "space-around",
+                "space-evenly",
+                "stretch",
+            ),
+        )
+    )
+    # The gap space between the children of the component.
+    gap = Prop(CSSField("gap", Size))
+    # Whether this component can scroll horizontally.
+    horizontal_scroll = Prop(CSSField("overflow-x", Scroll))
+    # Whether this component can scroll vertically.
+    vertical_scroll = Prop(CSSField("overflow-y", Scroll))
+    # Whether the components children should wrap around when they run
+    # out of space. For example, in a component with
+    # `direction="horizontal"`, children are placed side by side. When
+    # there are too many children to fit within the width of the
+    # component, and `wrap` is set to `"wrap"`, the children will wrap
+    # around onto a new "row" starting at the left edge again.
+    wrap = Prop(CSSField("flex-wrap", Optional(OneOf("wrap", "nowrap", "reverse"))))
+
+    def __init__(self):
+        """
+        `Boxy` cannot be instantiated.
+        """
+        raise Exception("`Boxy` cannot be instantiated.")

hyperdiv/component_mixins/interactive.py

@@ -0,0 +1,18 @@
+from ..prop_types import BoolEvent
+from ..prop import Prop
+
+
+class Interactive:
+    """
+    A collection of props defining how a component can generally be
+    interacted with. Currently only `clicked` is supported.
+    """
+
+    # Whether the component was clicked.
+    clicked = Prop(BoolEvent, False)
+
+    def __init__(self):
+        """
+        `Interactive` cannot be instantiated.
+        """
+        raise Exception("`Interactive` cannot be instantiated.")

hyperdiv/component_mixins/slottable.py

@@ -0,0 +1,43 @@
+from ..prop_types import HyperdivType
+from ..slot import Slot
+from ..prop import Prop
+
+
+class SlotTypeDef(HyperdivType):
+    """
+    The type of Hyperdiv component slots.
+    """
+
+    def parse(self, value):
+        if value is None:
+            return None
+        if not isinstance(value, Slot):
+            raise ValueError(f"Expected a Slot but got {type(value)}")
+        return value
+
+    def render(self, value):
+        if value is None:
+            return None
+        return value.ui_name
+
+    def __repr__(self):
+        return "SlotType"
+
+
+SlotType = SlotTypeDef()
+
+
+class Slottable:
+    """
+    A base class defining the `slot` prop, which allows a component to
+    be nested within a slot of a parent component. All Hyperdiv UI
+    components, except @component(text), support this interface.
+    """
+
+    slot = Prop(SlotType)
+
+    def __init__(self):
+        """
+        `Slottable` cannot be instantiated.
+        """
+        raise Exception("`Slottable` cannot be instantiated.")