hyperdivlite 0.1.9__py3-none-any.whl

hyperdiv/components/tab_group.py

@@ -0,0 +1,175 @@
+from ..prop_types import OneOf, StringEvent, Bool
+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
+from .scope import scope
+from .tab import tab
+
+
+class tab_group(Component, Styled):
+    """
+    `tab_group` groups together a set of @component(tab)
+    components. You can inspect the `active` prop on each tab to see
+    which tab is currently selected, and render content specific to
+    that tab.
+
+    ```py
+    with hd.tab_group() as tabs:
+        t1 = hd.tab("One")
+        t2 = hd.tab("Two")
+        t3 = hd.tab("Three")
+
+    with hd.box(padding=1):
+        if t1.active:
+            hd.text("One")
+        elif t2.active:
+            hd.text("Two")
+        else:
+            hd.text("Three")
+    ```
+
+    If you don't need control over how each tab is rendered, there is
+    a much terser alternative shorthand notation by passing the tab
+    names directly in the constructor, and using the `active` prop on
+    the tab group to inspect which tab is active, using the tab name:
+
+    ```py
+    tabs = hd.tab_group("One", "Two", "Three")
+
+    with hd.box(padding=1):
+        if tabs.active == "One":
+            hd.text("One")
+        elif tabs.active == "Two":
+            hd.text("Two")
+        else:
+            hd.text("Three")
+    ```
+
+    ### Vertical tabs
+
+    ```py
+    with hd.hbox():
+        tabs = hd.tab_group(
+            "One", "Two", "Three",
+            placement="start"
+        )
+        with hd.box(padding=1):
+            if tabs.active == "One":
+                hd.text("One")
+            elif tabs.active == "Two":
+                hd.text("Two")
+            else:
+                hd.text("Three")
+    ```
+    """
+
+    _name = "tab_group"
+    _tag = "sl-tab-group"
+
+    # The placement of the tabs:
+    #
+    # * top: the tabs are laid out horizontally, the underline is
+    #   rendered below the tabs, and the tab group is placed at the
+    #   top of the tab group container.
+    #
+    # * bottom: the tabs are laid out horizontally, the underline is
+    #   rendered above the tabs, and the tab group is placed at the
+    #   bottom of the tab group container.
+    #
+    # * start: the tabs are laid out vertically, the underline is
+    #   rendered to the right of the tabs, and the tab group is placed
+    #   at the start of the tab group container.
+    #
+    # * end: the tabs are laid out vertically, the underline is
+    #   rendered to the left of the tabs, and the tab group is placed
+    #   at the end of the tab group container.
+    placement = Prop(OneOf("top", "bottom", "start", "end"), "top")
+    # By default, when navigating with the keyboard, tabs are
+    # automatically activated when pressing the left or right arrow
+    # keys. When activation is set to `"manual"`, you have to press
+    # Space or Enter to activate the focused tab.
+    activation = Prop(OneOf("auto", "manual"), "auto")
+    # Whether to render scroll buttons when the tabs overflow.
+    no_scroll_controls = Prop(Bool, False)
+    _active_tab_key = Prop(StringEvent, "")
+
+    nav = Slot()
+
+    base_style = Prop(BasePart())
+    nav_style = Prop(StylePart("nav"))
+    tabs_style = Prop(StylePart("tabs"))
+    active_tab_indicator_style = Prop(StylePart("active-tab-indicator"))
+    body_style = Prop(StylePart("body"))
+    scroll_button_style = Prop(StylePart("scroll-button"))
+    scroll_button_start_style = Prop(StylePart("scroll-button--start"))
+    scroll_button_end_style = Prop(StylePart("scroll-button--end"))
+    scroll_button_base_style = Prop(StylePart("scroll-button__base"))
+
+    def __init__(self, *tabs, **kwargs):
+        self.tabs = []
+        self.active_tab = None
+        self.closed_tab = None
+
+        super().__init__(**kwargs)
+
+        if tabs:
+            with self:
+                for tab_label in tabs:
+                    with scope(tab_label):
+                        tab(tab_label, font_size=self.font_size)
+
+    @property
+    def closed(self):
+        return self.closed_tab.label if self.closed_tab else None
+
+    @property
+    def active(self):
+        return self.active_tab.label if self.active_tab else None
+
+    def _collect_child(self, child):
+        if isinstance(child, tab):
+            if child.slot and child.slot != self.nav:
+                raise Exception("`tab` cannot be in a slot other than `tab_group.nav`.")
+            if not child.slot:
+                child.slot = self.nav
+
+        super()._collect_child(child)
+
+        if not isinstance(child, tab):
+            return
+
+        self.tabs.append(child)
+
+        if self._active_tab_key:
+            # Setting a new active tab. Reminder: `active_child_key` is
+            # only set for one frame.
+            if child._key == self._active_tab_key:
+                child.active = True
+                self.active_tab = child
+            elif child.active:
+                # Make the prior active tab inactive.
+                child.active = False
+        else:
+            # Tentatively assume the first tab is active
+            if not self.active_tab:
+                self.active_tab = child
+            # But if we find an actually active tab later, set that
+            # one as active.
+            if child.active:
+                self.active_tab = child
+
+        if child.closed_clicked:
+            self.closed_tab = child
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # On body exit, if the tab we assumed would be active
+        # isn't active, then set it to active. This happens when there
+        # are no active tabs, and we force the first tab to be active.
+        super().__exit__(exc_type, exc_val, exc_tb)
+        if self.active_tab and not self.active_tab.active:
+            self.active_tab.active = True
+
+
+tabs = tab_group

hyperdiv/components/table.py

@@ -0,0 +1,217 @@
+from ..component_base import Component
+from ..component_mixins.styled import Styled
+from ..prop_types import CSSField, OneOf, Int
+from ..prop import Prop
+from .common.label_component import LabelComponent
+
+
+class table(Component, Styled):
+    """An HTML table component. Using @component(thead),
+    @component(tbody), @component(tfoot), @component(tr),
+    @component(td), you can manually assemble tables.
+
+    ```py
+    with hd.table():
+        # Table header
+        with hd.thead():
+            # Header row
+            with hd.tr():
+                hd.td("Name")
+                hd.td("Age")
+                hd.td()
+        # Table body
+        with hd.tbody():
+            # Body rows
+            with hd.tr():
+                hd.td("Amy")
+                hd.td(28)
+                with hd.td():
+                    with hd.box(align="end"):
+                        hd.button("Delete Amy")
+            with hd.tr():
+                hd.td("Jim")
+                hd.td(35)
+                with hd.td():
+                    with hd.box(align="end"):
+                        hd.button("Delete Jim")
+        # Table footer
+        with hd.thead():
+            # Footer row
+            with hd.tr():
+                hd.td("Average Age")
+                hd.td((28+35)/2)
+                hd.td()
+    ```
+
+    Each of the table sections is optional.
+
+    The direct children of `table` should be @component(thead),
+    @component(tbody), or @component(tfoot), at most one of each.
+
+    However, browsers are generally lenient and allow omitting the
+    @component(tbody) wrapper, so you can nest rows (@component(tr)s)
+    directly within `table`.
+
+    ```py
+    with hd.table():
+        with hd.tr():
+            hd.td("Amy")
+            hd.td(28)
+        with hd.tr():
+            hd.td("Jim")
+            hd.td(35)
+    ```
+    """
+
+    _name = "table"
+    _tag = "table"
+
+    border_collapse = Prop(
+        CSSField("border-collapse", OneOf("collapse", "separate")),
+        "collapse",
+    )
+
+    def __init__(
+        self,
+        *,
+        border="1px solid neutral-100",
+        **kwargs,
+    ):
+        super().__init__(border=border, **kwargs)
+
+
+class tr(Component, Styled):
+    """
+    A table row container. To be used with @component(table).
+
+    Its direct children should be @component(td)s.
+    """
+
+    _name = "tr"
+    _tag = "tr"
+
+
+class td(LabelComponent):
+    """
+    A table cell container. To be used with @component(table).
+
+    Arbitrary components can be nested within a `td`. If you want to
+    control the alignment of children, you should place a
+    @component(box) in the `td`, and the children inside that
+    box. `td` itself does not expose box props.
+
+    ## Spans
+
+    `td` supports props `colspan` and `rowspan` that allow a table
+    cell to take up the space otherwise occupied by cells to the
+    right, or cells below, respectively.
+
+    Here's a 3 rows x 2 columns table:
+
+    ```py
+    with hd.table():
+        with hd.tr():
+            hd.td("(0, 0)")
+            hd.td("(0, 1)")
+        with hd.tr():
+            hd.td("(1, 0)")
+            hd.td("(1, 1)")
+        with hd.tr():
+            hd.td("(2, 0)")
+            hd.td("(2, 1)")
+    ```
+
+    And using `colspan` and `rowspan`:
+
+    ```py
+    with hd.table():
+        with hd.tr():
+            hd.td("(0, 0) and (0, 1)", colspan=2)
+            # No td for (0, 1)
+        with hd.tr():
+            hd.td("(1, 0) and (2, 0)", rowspan=2)
+            hd.td("(1, 1)")
+        with hd.tr():
+            # No td for (2, 0)
+            hd.td("(2, 1)")
+    ```
+
+    By default, `rowspan` and `colspan` are `1`, indicating that the
+    cell takes up one cell's worth of space.
+    """
+
+    _name = "td"
+    _tag = "td"
+
+    # The horizontal/rightward span of this cell.
+    colspan = Prop(Int, 1)
+    # The vertical/downward span of this cell.
+    rowspan = Prop(Int, 1)
+
+    def __init__(
+        self,
+        *label,
+        border="1px solid neutral-100",
+        padding=(0.5, 0.8, 0.5, 0.8),
+        **kwargs,
+    ):
+        super().__init__(*label, border=border, padding=padding, **kwargs)
+
+
+class thead(Component, Styled):
+    """
+    A table header container. To be used with @component(table).
+
+    Its direct children should be @component(tr)s.
+    """
+
+    _name = "thead"
+    _tag = "thead"
+
+    def __init__(
+        self,
+        *,
+        background_color="neutral-50",
+        font_weight="bold",
+        **kwargs,
+    ):
+        super().__init__(
+            background_color=background_color,
+            font_weight=font_weight,
+            **kwargs,
+        )
+
+
+class tfoot(Component, Styled):
+    """
+    A table footer container. To be used with @component(table).
+
+    Its direct children should be @component(tr)s.
+    """
+
+    _name = "tfoot"
+    _tag = "tfoot"
+
+    def __init__(
+        self,
+        *,
+        background_color="neutral-50",
+        font_weight="bold",
+        **kwargs,
+    ):
+        super().__init__(
+            background_color=background_color,
+            font_weight=font_weight,
+            **kwargs,
+        )
+
+
+class tbody(Component, Styled):
+    """
+    A table body container. To be used with @component(table).
+
+    Its direct children should be @component(tr)s.
+    """
+
+    _name = "tbody"
+    _tag = "tbody"

hyperdiv/components/tag.py

@@ -0,0 +1,77 @@
+from ..prop_types import OneOf, Bool, BoolEvent
+from ..prop import Prop
+from ..component_mixins.interactive import Interactive
+from ..style_part import BasePart, StylePart
+from .common.label_component import LabelComponent
+from .common.shoelace_types import ShoelaceSize
+
+
+class tag(LabelComponent, Interactive):
+    """
+    A tag component similar to @component(badge).
+
+    ```py
+    state = hd.state(removed=False)
+
+    with hd.box(gap=1):
+        hd.tag("A tag")
+        hd.tag("A danger tag", variant="danger")
+        hd.tag("A small tag", size="small")
+        hd.tag("A large tag", size="large")
+        hd.tag(
+            "A warning pill tag",
+            variant="warning",
+            pill=True
+        )
+    ```
+
+    ### Removable tags
+
+    When passing `removable=True`, the tag renders a close button.
+    The event prop `removed` fires when the button is clicked.
+
+    ```py
+    state = hd.state(removed=False)
+
+    if not state.removed:
+        tag = hd.tag(
+            "A removable tag",
+            removable=True
+        )
+        if tag.removed:
+            state.removed = True
+    ```
+
+    """
+
+    _name = "tag"
+    _tag = "sl-tag"
+
+    # The variant of the tag.
+    variant = Prop(
+        OneOf(
+            "primary",
+            "success",
+            "neutral",
+            "warning",
+            "danger",
+            "text",
+        ),
+        "neutral",
+    )
+    # The size of the tag.
+    size = Prop(ShoelaceSize, "medium")
+    # Whether the tag is rendered as a pill.
+    pill = Prop(Bool, False)
+    # Whether a closed button is rendered in the tag.
+    removable = Prop(Bool, False)
+    # Event prop that fires when the closed button is clicked.
+    removed = Prop(BoolEvent, False)
+
+    base_style = Prop(BasePart())
+    content_style = Prop(StylePart("content"))
+    remove_button_style = Prop(StylePart("remove-button"))
+    remove_button_base_style = Prop(StylePart("remove-button__base"))
+
+    def __init__(self, *label, width="fit-content", **kwargs):
+        super().__init__(*label, width=width, **kwargs)

hyperdiv/components/task.py

@@ -0,0 +1,232 @@
+import asyncio
+from ..prop_types import Int, BoolEvent
+from ..prop import Prop
+from ..frame import AppRunnerFrame
+from ..debug import logger
+from .async_command import async_command
+
+
+def run_asynchronously(result_callback, fn, *args, **kwargs):
+    frame = AppRunnerFrame.current()
+
+    if asyncio.iscoroutinefunction(fn):
+        # If task is an async function, run it on the ioloop
+        async def run_async_task():
+            try:
+                with frame.task_frame():
+                    try:
+                        result = await fn(*args, **kwargs)
+                        result_callback(result)
+                    except Exception as e:
+                        logger.exception("Task Failure")
+                        result_callback(error=str(e))
+            except Exception as e:
+                logger.exception(f"Internal Error: {e}")
+
+        frame.run_task_on_ioloop(run_async_task())
+
+    else:
+        # If task is a regular function, run it in the threadpool
+        def run_task():
+            try:
+                with frame.task_frame():
+                    try:
+                        result = fn(*args, **kwargs)
+                        result_callback(result=result)
+                    except Exception as e:
+                        logger.exception("Task Failure")
+                        result_callback(error=str(e))
+            except Exception as e:
+                logger.exception(f"Internal Error: {e}")
+
+        frame.run_task_in_threadpool(run_task)
+
+
+class task(async_command):
+    """
+    `task` enables running user functions asynchronously, without
+    occupying the main UI thread. Functions doing significant work
+    or waiting on I/O may be good candidates to run with `task`.
+
+    The task function runs concurrently with the main app
+    function. While a task function is running, the main app function
+    can run and update the UI independently.
+
+    The main app function can inspect the state of the running task
+    using the props `running`, `done`, `error`, `result` and
+    `finished`.
+
+    The task function cannot instantiate UI components like
+    @component(button) -- it cannot create UIs. However, it can update
+    state. You can pass a UI or state component into the task function
+    and the task can read and update its props. The updates propagate
+    immediately and can cause the main app function to re-run, and
+    update the UI, while the task function is still running.
+
+    Tasks can also instantiate global state -- components defined with
+    @component(global_state) -- and inspect/update the global state.
+
+    ## Result Caching
+
+    When running a function with `task`, the return value of the
+    function will be cached in the task's `result` prop. Subsequent
+    calls to `task.run` will not re-run the function, unless you call
+    `rerun` or `clear`. Clearing a task will cause a subsequent call
+    to `run()` to run the function again.
+
+    In this example, when we click `Update`, the app-reruns, and since
+    the task is cleared, `task.run(get_timestamp)` will run the
+    `get_timestamp` function again.
+
+    ```py
+    def get_timestamp():
+        import time
+        return time.time()
+
+    task = hd.task()
+    task.run(get_timestamp)
+
+    hd.text("Last timestamp:", task.result)
+
+    if hd.button("Update").clicked:
+        task.clear()
+    ```
+
+    ## Using `rerun`
+
+    As an alternative to using `run` and `clear`, you can use `rerun`,
+    which clears the task and reruns the task function. `rerun` should
+    be run only in response to an event, like a click or a change
+    event.
+
+    ```py
+    def increment(state):
+        state.count += 1
+
+    state = hd.state(count=0)
+
+    task = hd.task()
+
+    hd.text("Count:", state.count)
+
+    if hd.button("Increment").clicked:
+        task.rerun(increment, state)
+    ```
+
+    ## Async Functions
+
+    `task` supports both normal functions and `async def`
+    functions. Normal functions are run in a threadpool, and `async
+    def` functions are run on an ioloop which runs on a separate
+    "ioloop thread".
+
+    ```py
+    async def my_function(state):
+        import asyncio
+        await asyncio.sleep(1)
+        state.count += 1
+
+    state = hd.state(count=0)
+
+    task = hd.task()
+
+    hd.text("Count:", state.count)
+
+    if hd.button(
+        "Increment",
+        disabled=task.running
+    ).clicked:
+        task.rerun(my_function, state)
+    ```
+
+    Whenever you click the button, a task is launched that increments
+    the count one second later. This example also shows how to use the
+    task state to display different UI states. In this case, the
+    button is disabled while the task is running.
+
+    ## Displaying Interstitials
+
+    The task state can be used to display "Loading" interstitials
+    while the task is running.
+
+    ```py
+    async def get_users():
+        import asyncio
+        await asyncio.sleep(1)
+        return ["Billy", "Molly"]
+
+    users_task = hd.task()
+    users_task.run(get_users)
+
+    if hd.button("Load").clicked:
+        users_task.clear()
+
+    if not users_task.done:
+        hd.spinner()
+    else:
+        hd.text(users_task.result)
+    ```
+
+    ## Concurrency
+
+    Tasks run concurrently with each other and the app function. Prop
+    reads and writes are automatically protected by a lock, but you
+    may need to use your own locks if you need coarser-granularity
+    locking. You can store a lock in state and pass that state to tasks.
+
+    """
+
+    _run_number = Prop(Int, 0)
+    finished = Prop(BoolEvent, False)
+
+    def __init__(self, *, key=None):
+        super().__init__(key=key)
+
+    def run(self, fn, *args, **kwargs):
+        """
+        Run `fn(*args, **kwargs)` on a separate thread (or ioloop if the
+        function is `async`).
+        """
+
+        run_number = self._run_number
+
+        def result_callback(result=None, error=None):
+            if self._run_number != run_number:
+                logger.warn(
+                    f"The task {fn}({args}, {kwargs}) was cleared/restarted "
+                    "before the previous run could finish."
+                )
+                return
+            self.result = result
+            self.error = error
+            self.done = True
+            self.running = False
+            self.trigger_event("finished", True)
+
+        if not self.running and not self.done:
+            self.running = True
+            run_asynchronously(result_callback, fn, *args, **kwargs)
+
+    def rerun(self, fn, *args, **kwargs):
+        """Just like `run` but calls `self.clear()` before running."""
+
+        self.clear()
+        self.run(fn, *args, **kwargs)
+
+    def clear(self):
+        """
+        Resets the props of the task to initial values. If the task is
+        `done`, clearing it will allow it to run again. Note that if
+        an instance of the task is running at the time `clear()` is
+        called, that instance will be ignored, but it will still run
+        to completion.
+
+        Note that the `result` prop is not cleared, allowing the app
+        to keep rendering the previous result until the `result` prop
+        is updated with the data of the new run.
+        """
+
+        if self.running:
+            logger.warn("Clearing running task.")
+        self._run_number += 1
+        super().clear()