cave_utils.api.appBar

  1"""
  2The app bar is a key element of the CAVE App, positioned on the left or
  3right side of the screen. It provides actions that allow users to
  4navigate between [pages][], launch [panes][], and interact with the
  5CAVE API through [predefined][] or [custom][] commands.
  6
  7If specified, both left and right side app bars can be displayed
  8simultaneously.
  9
 10[pages]: pages.html
 11[panes]: panes.html
 12[predefined]: #appBar_data_star.spec
 13[custom]: #appBar_data_star.spec
 14"""
 15
 16from cave_utils.api_utils.validator_utils import ApiValidator, CustomKeyValidator
 17import type_enforced
 18
 19
 20@type_enforced.Enforcer
 21class appBar(ApiValidator):
 22    """
 23    The app bar is located under the path **`appBar`**.
 24    """
 25
 26    @staticmethod
 27    def spec(data: dict = dict(), **kwargs):
 28        """
 29        @private
 30        Arguments:
 31
 32        * **`data`**: `[dict]` = `{}` → The data to pass to `appBar.data.*`.
 33        """
 34        return {"kwargs": kwargs, "accepted_values": {}}
 35
 36    def __extend_spec__(self, **kwargs):
 37        data = self.data.get("data", {})
 38        CustomKeyValidator(
 39            data=data, log=self.log, prepend_path=["data"], validator=appBar_data_star, **kwargs
 40        )
 41
 42
 43@type_enforced.Enforcer
 44class appBar_data_star(ApiValidator):
 45    """
 46    The app bar data is located under the path **`appBar.data`**.
 47    """
 48
 49    @staticmethod
 50    def spec(
 51        icon: str,
 52        type: str,
 53        bar: str,
 54        variant: str | None = None,
 55        color: str | None = None,
 56        apiCommand: str | None = None,
 57        apiCommandKeys: list[str] | None = None,
 58        **kwargs,
 59    ):
 60        """
 61        Arguments:
 62
 63        * **`icon`**: `[str]` → An icon to display in the center of the action element.
 64            * **Note**: It must be a valid icon name from the [react-icons][] bundle, preceded by the abbreviated name of the icon library source.
 65            * **Example**: `"md/MdRocket"`.
 66        * **`type`**: `[str]` → The type of object displayed when the action is triggered.
 67            * **Accepted Values**:
 68                * `"session"`: The Session Pane
 69                    * If you use this type, your field id must be `"session"`.
 70                * `"settings"`: The Application Settings Pane
 71                    * If you use this type, your field id must be `"settings"`.
 72                * `"button"`: A button that allows you to send a command to the CAVE API
 73                * `"pane"`: A [custom pane][]
 74                * `"page"`: A [page][]
 75        * **`bar`**: `[str]` → The location of the action element.
 76            * **Accepted Values**:
 77                * `"upperLeft"`: Upper section of the left-side bar
 78                * `"lowerLeft"`: Lower section of the left-side bar
 79                * `"upperRight"`: Upper section of the right-side bar
 80                * `"lowerRight"`: Lower section of the right-side bar
 81                * `"none"`: Do not display the action element in the app bar
 82                    - This is useful to hide predefined appBar buttions like the `session` or `settings` panes.
 83        * **`variant`**: `[str]` = `None` → The variant of the button.
 84            * **Accepted Values**:
 85                * When **`type`** == `"pane"`:
 86                    * `"modal"`: A [modal pane][]
 87                    * `"wall"`: A [wall pane][]
 88                * Otherwise:
 89                    * `None`
 90        * **`color`**: `[str]` = `<system-default-value>` &rarr;
 91            * The color of the button. If omitted, the default value is set by the system.
 92            * **Note**: It must be a valid RGBA string.
 93            * **Example**: `"rgba(255, 255, 255, 1)"`.
 94        * **`apiCommand`**: `[str]` = `None` &rarr; The name of the [API command][] to trigger.
 95        * **`apiCommandKeys`**: `[list[str]]` = `None` &rarr;
 96            * The root API keys to pass to your `execute_command` function if an
 97            `apiCommand` is provided. If omitted, all API keys are
 98            passed to `execute_command`.
 99
100        [page]: pages.html
101        [pane]: panes.html
102        [modal pane]: panes.html
103        [wall pane]: panes.html
104        [API command]: #appBar_data_star.spec
105        [react-icons]: https://react-icons.github.io/react-icons/search
106        """
107        return {
108            "kwargs": kwargs,
109            "accepted_values": {
110                "type": ["session", "settings", "button", "pane", "page"],
111                "variant": ["modal", "wall"] if type == "pane" else [],
112                "bar": ["upperLeft", "lowerLeft", "upperRight", "lowerRight", "none"],
113            },
114        }
115
116    def __extend_spec__(self, **kwargs):
117        color = self.data.get("color")
118        if color:
119            self.__check_color_string_valid__(color_string=color, prepend_path=["color"])
120        # Validate pageIds
121        bar_type = self.data.get("type")
122        if bar_type == "page":
123            self.__check_subset_valid__(
124                subset=[kwargs.get("CustomKeyValidatorFieldId")],
125                valid_values=kwargs.get("page_validPageIds", []),
126                prepend_path=[],
127            )
128        if bar_type == "pane":
129            self.__check_subset_valid__(
130                subset=[kwargs.get("CustomKeyValidatorFieldId")],
131                valid_values=kwargs.get("pane_validPaneIds", []),
132                prepend_path=[],
133            )
134        if bar_type == "session":
135            if kwargs.get("CustomKeyValidatorFieldId") != "session":
136                self.__error__(
137                    msg=f"When `type` is 'session', the only valid id for this `appBar.data` item is 'session'. Received: '{kwargs.get('CustomKeyValidatorFieldId')}'",
138                    path=[],
139                )
140        if bar_type == "settings":
141            if kwargs.get("CustomKeyValidatorFieldId") != "settings":
142                self.__error__(
143                    msg=f"When `type` is 'settings', the only valid id for this `appBar.data` item is 'settings'. Received: '{kwargs.get('CustomKeyValidatorFieldId')}'",
144                    path=[],
145                )