diff --git a/shiny_semantic/elements/button.py b/shiny_semantic/elements/button.py index 3f25a6d..cf36da0 100644 --- a/shiny_semantic/elements/button.py +++ b/shiny_semantic/elements/button.py @@ -15,6 +15,31 @@ def button( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate an HTML button element with optional icon and attributes. + + This function generates an HTML button element with various customization options, + including providing an icon, setting CSS classes, and adding additional attributes. + + Args: + id (str): The unique identifier for the button. + label (str, optional): The text label to display on the button. If not provided, the button will be icon-only. + icon (TagChildArg, optional): An HTML element representing an icon to be displayed on the button. + class_ (str, optional): Additional CSS classes to be applied to the button element. + **kwargs (TagAttrArg): Additional attributes to be added to the button element. + + Returns: + str: A string representing the generated HTML button element. + + Example: + # Creating a button with text label + button_with_label = button("my_button", label="Click Me", class_="primary", onclick="handle_click()") + + # Creating an icon-only button + icon_element = tags.i(class_="fas fa-search") + icon_button = button("search_button", icon=icon_element, class_="icon-button") + + """ class_name = f"ui {class_ or ''} button" return tags.button( @@ -33,6 +58,34 @@ def update_button( icon_name: Optional[str] = None, session: Optional[Session] = None, ): + """ + Update a button in an active session. + + This function updates the properties of a button element in a given active session. + The input_id is used to identify the specific button element to be updated. The label + and icon_name arguments can be provided to change the label text and icon of the button, + respectively. + + Args: + input_id (str): The ID of the button element to be updated. + label (str, optional): The new label text for the button. If not provided, the label remains unchanged. + icon_name (str, optional): The name of the icon to be displayed on the button. If not provided, + the icon remains unchanged. + session (Session, optional): An active session instance in which the button is located. + If not provided, the function attempts to use the default active session. + + Returns: + None + + Example: + update_button( + "my_button", + label = "Click Me", + icon_name = "icon-check", + session = session + ) + + """ session = require_active_session(session) msg = { "label": label, diff --git a/shiny_semantic/elements/container.py b/shiny_semantic/elements/container.py index ee17057..eac211a 100644 --- a/shiny_semantic/elements/container.py +++ b/shiny_semantic/elements/container.py @@ -10,6 +10,36 @@ def container( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Create a container HTML element with optional classes and attributes. + + This function generates an HTML
element with the specified + content elements as children. + It can be used to encapsulate content within a container, often used + in web design frameworks. + + Args: + *children (TagChildArg): Variable number of content elements + to be included inside the container. + class_ (str, optional): Additional classes to be added + to the container's class attribute. + Default is None. + **kwargs (TagAttrArg): Additional attributes to be added + to the container element. + + Returns: + str: A string representing the generated HTML container element. + + Example: + container_content = tags.p("This is content inside the container.") + container_element = container( + container_content, + class_ = "my-custom-class", + id = "container1" + ) + print(container_element) + + """ return tags.div( *children, class_=squash_whitespace(f"ui {class_ or ''} container"), diff --git a/shiny_semantic/elements/divider.py b/shiny_semantic/elements/divider.py index 4446ee6..cf390b8 100644 --- a/shiny_semantic/elements/divider.py +++ b/shiny_semantic/elements/divider.py @@ -10,6 +10,32 @@ def divider( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate a UI divider element with optional content and attributes. + + This function creates a
element styled as a UI divider, commonly used in user interfaces + to visually separate content. You can provide optional children elements to include content + within the divider, and you can also customize the styling and attributes of the divider. + + Args: + *children (TagChildArg): Variable number of HTML content elements to be placed inside the divider. + class_ (str, optional): Additional CSS class to apply to the divider for custom styling. + **kwargs (TagAttrArg): Additional HTML attributes to apply to the
element. + + Returns: + str: A string representing the generated HTML
element. + + Example: + div_content = tags.p("This is some content within the divider.") + div_attributes = {"id": "my-divider", "data-role": "separator"} + divider_element = divider( + div_content, + class_ = "custom-divider", + **div_attributes + ) + print(divider_element) + + """ return tags.div( *children, class_=squash_whitespace(f"ui {class_ or ''} divider"), diff --git a/shiny_semantic/elements/emoji.py b/shiny_semantic/elements/emoji.py index 26246d9..d9c7044 100644 --- a/shiny_semantic/elements/emoji.py +++ b/shiny_semantic/elements/emoji.py @@ -4,4 +4,27 @@ def emoji(emoji_name: str, *, class_: Optional[str] = None, **kwargs: TagAttrArg): + """ + Generate an (emphasis) HTML tag representing an emoji. + + This function creates an HTML tag that displays an emoji by using its name. The emoji name is enclosed in colons + and should match a valid emoji name supported by the underlying system or library. + + Args: + emoji_name (str): The name of the emoji, without colons. For example, "smile" for ":smile:". + class_ (str, optional): CSS class to apply to the tag for styling purposes. Defaults to None. + **kwargs: Additional keyword arguments that will be added as attributes to the tag. + + Returns: + str: A string representing the generated tag containing the specified emoji. + + Example: + emoji_tag = emoji( + "smile", + class_ = "highlight", + title = "Happy Face" + ) + print(emoji_tag) + + """ return tags.em(data_emoji=f":{emoji_name}:", class_=class_, **kwargs) diff --git a/shiny_semantic/elements/flag.py b/shiny_semantic/elements/flag.py index 32bb1e9..d4c7ddf 100644 --- a/shiny_semantic/elements/flag.py +++ b/shiny_semantic/elements/flag.py @@ -6,6 +6,29 @@ def flag(country: str, *, class_: Optional[str] = None, **kwargs: TagAttrArg): + """ + Generate an inline flag icon element for a specified country. + + This function generates an inline element with a CSS class representing a flag icon + for the specified country. Additional HTML attributes can be provided using keyword arguments. + + Args: + country (str): The name of the country for which the flag icon should be displayed. + class_ (str, optional): Additional CSS class to be applied to the flag icon. Defaults to None. + **kwargs: Additional HTML attributes to be added to the element. + + Returns: + str: A string representing the generated element with the flag icon and attributes. + + Example: + flag_element = flag( + "usa", + class_ = "large-flag", + title = "USA Flag" + ) + print(flag_element) + + """ return tags.i( class_=squash_whitespace(f"{class_ or ''} {country} flag"), **kwargs, diff --git a/shiny_semantic/elements/header.py b/shiny_semantic/elements/header.py index 98972c6..decdc62 100644 --- a/shiny_semantic/elements/header.py +++ b/shiny_semantic/elements/header.py @@ -16,6 +16,27 @@ def header( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate a semantic header element with optional UI classes. + + This function creates an HTML
element with the specified content children and optional + UI classes for styling. The generated
acts as a header element, often used to display + headings or titles within a user interface. + + Args: + *children (TagChildArg): Variable number of HTML content elements to be included within the header. + class_ (str, optional): Additional CSS classes to be applied to the header element. + **kwargs (TagAttrArg): Additional keyword arguments to be added as attributes to the header element. + + Returns: + str: A string representing the generated HTML header element. + + Example: + header_content = tags.h1("Welcome to My App!") + header_element = header(header_content, class_="highlight", id="app-header") + print(header_element) + + """ return tags.div( *children, class_=squash_whitespace(f"ui {class_ or ''} header"), @@ -28,6 +49,31 @@ def subheader( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Create a subheader HTML element with optional classes and attributes. + + This function generates an HTML
element to represent a subheader. It allows + specifying child elements to be included within the subheader, along with optional + classes and additional HTML attributes. + + Args: + *children (TagChildArg): Variable number of child elements to be included within the subheader. + class_ (str, optional): CSS class(es) to be applied to the subheader. Multiple classes can be provided + by separating them with a space. The "sub header" class is automatically added to the specified classes. + **kwargs (TagAttrArg): Additional HTML attributes to be applied to the subheader. + + Returns: + str: A string representing the generated subheader HTML element. + + Example: + subheader_element = subheader( + tags.h2("Important Information"), + class_ = "highlight", + id = "info-header" + ) + print(subheader_element) + + """ return tags.div( *children, class_=squash_whitespace(f"{class_ or ''} sub header"), diff --git a/shiny_semantic/elements/icon.py b/shiny_semantic/elements/icon.py index 719f169..ef52631 100644 --- a/shiny_semantic/elements/icon.py +++ b/shiny_semantic/elements/icon.py @@ -11,6 +11,35 @@ def icon( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate an HTML element with an icon. + + This function creates an HTML element that is commonly used for displaying icons using icon classes. + The icon_name parameter specifies the icon class to be applied to the element. + Additional attributes can be passed using the kwargs parameter. + + Args: + icon_name (str): The icon class name to be applied to the element. + class_ (str, optional): Additional CSS class(es) to be added to the element. + If not provided, only the icon class specified by icon_name will be used. + **kwargs: Additional keyword arguments representing attributes to be added to the element. + + Returns: + dominate.tags.i: An HTML element with the specified icon class and optional attributes. + + Example: + # Creating a simple icon element + simple_icon = icon("fa fa-star") + + # Creating an icon element with additional classes and attributes + custom_icon = icon( + "my-icon", + class_ = "custom-icon", + title = "Custom Icon", + aria_label = "Custom" + ) + + """ return tags.i( class_=squash_whitespace(f"{class_ or ''} {icon_name} icon"), **kwargs, diff --git a/shiny_semantic/elements/input.py b/shiny_semantic/elements/input.py index 0aa4e8e..70ceda4 100644 --- a/shiny_semantic/elements/input.py +++ b/shiny_semantic/elements/input.py @@ -18,11 +18,41 @@ def semantic_input( semantic_label_class: Optional[str] = None, **kwargs: TagAttrArg, ): - """Keyword arguments (**kwargs) include all html attributes - relevant to the input tag, including, for example, `min`, `max` and `step` - in case of input type="number", as well as `class_` that is passed directly - to the input tag, as opposed to the `semantic_class` that is passed to the - enclosing div element. + """ + Generate a semantic-styled input element with optional label and icon. + + This function generates a customizable HTML input element with a semantic styling, + allowing for the addition of icons, labels, and various attributes. The input + element is enclosed in a
element with appropriate classes for styling. + + Args: + id (str): Identifier for the input element. + value (Union[str, float], optional): Initial value of the input element. Defaults to an empty string. + placeholder (str, optional): Placeholder text to display in the input element. + icon (TagChildArg, optional): Icon to display with the input. Can be an HTML element or Tag object. + type (str, optional): Type of the input element (e.g., "text", "number", "password"). Defaults to "text". + semantic_class (str, optional): Additional classes to apply to the enclosing
element for styling. + semantic_label (str, optional): Label text to display above the input element. + semantic_label_class (str, optional): Additional classes to apply to the label element for styling. + **kwargs (TagAttrArg): includes all html attributes relevant to the input tag, including, + for example, `min`, `max` and `step` in case of input type = "number", + as well as `class_` that is passed directly to the input tag, + as opposed to the `semantic_class` that is passed to the enclosing div element. + + Returns: + str: A string representing the generated HTML code. + + Example: + input_with_icon = semantic_input( + id = "username", + placeholder = "Enter your username", + icon = tags.i(class_ = "user icon"), + semantic_label = "Username", + semantic_label_class = "blue", + required = True, + ) + print(input_with_icon) + """ # Enclosing div's class if semantic_class is None: diff --git a/shiny_semantic/elements/segment.py b/shiny_semantic/elements/segment.py index f27af52..65b6517 100644 --- a/shiny_semantic/elements/segment.py +++ b/shiny_semantic/elements/segment.py @@ -10,6 +10,31 @@ def segment( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate a UI segment element in HTML. + + This function creates a UI segment element, often used in web interfaces to visually + separate and group content. The segment can contain various child elements, such as text, + images, buttons, etc. It supports custom CSS classes and additional attributes. + + Args: + *children (TagChildArg): Variable number of child elements to be included within the segment. + class_ (str, optional): Additional CSS class for the segment element. + **kwargs (TagAttrArg): Additional attributes to be added to the segment element. + + Returns: + str: A string representing the generated segment element in HTML. + + Example: + content = tags.p("This is the content of the segment.") + segment_element = segment( + content, + class_ = "custom-segment", + id = "segment-1" + ) + print(segment_element) + + """ return tags.div( *children, class_=squash_whitespace(f"ui {class_ or ''} segment"), diff --git a/shiny_semantic/modules/checkbox.py b/shiny_semantic/modules/checkbox.py index a561ac3..3a59f52 100644 --- a/shiny_semantic/modules/checkbox.py +++ b/shiny_semantic/modules/checkbox.py @@ -17,7 +17,37 @@ def checkbox( class_: Optional[str] = None, **kwargs, ): + """ + Generate an HTML checkbox or radio input element with an associated label. + + This function creates an HTML checkbox or radio input element along with a label. + The checkbox/radio input is associated with its label through the 'for' attribute, + and can be customized with additional attributes and CSS classes. + + Args: + id (str): The unique identifier for the input element. Will also be used to generate + the 'for' attribute in the associated label. + label (str): The text label that will be displayed next to the checkbox/radio input. + value (bool, optional): The initial state of the checkbox/radio input. Defaults to False. + type (str, optional): The type of input element. Use 'radio' for radio buttons. + name (str, optional): The name attribute for the input element. Defaults to the id value. + class_ (str, optional): Additional CSS classes to apply to the input element. + **kwargs: Additional keyword arguments that will be added as attributes to the generated +
element containing the checkbox/radio input and label. + + Returns: + str: A string representing the generated HTML structure. + + Example: + checkbox_element = checkbox( + "checkbox1", + "Enable feature", + value = True, + class_ = "highlight" + ) + print(checkbox_element) + """ class_ = f"{class_ or ''}" if value: class_ = f"{class_} checked" @@ -53,6 +83,44 @@ def checkbox_group( position: Optional[str] = "grouped", class_: Optional[str] = None, ): + """ + Generate a group of checkboxes with a common label and layout. + + This function generates a group of checkboxes, allowing users to select one or + more options. It creates a styled UI form for the checkboxes with a common label. + + Args: + id (str): Unique identifier for the checkbox group. + label (str): The label text displayed above the checkbox group. + choices (Union[list[str], dict[str, str]]): Choices available for selection. It can be a list of strings + or a dictionary with keys as values and values as labels. + selected (Optional[Union[list[str], tuple[str], str]]): Initially selected options. It can be a list of + strings, a tuple of strings, or a single string. Defaults to an empty list. + type (Optional[str]): Type of checkboxes. Possible values are "radio" or None (for regular checkboxes). + Defaults to None. + position (Optional[str]): Positioning style of the checkboxes within the group. Possible values are + "grouped" or "inline". Defaults to "grouped". + class_ (Optional[str]): Additional CSS class to be applied to the checkbox group container. Defaults to None. + + Returns: + str: A string representing the HTML structure of the generated checkbox group. + + Raises: + Exception: If type is "radio" and multiple options are selected, as radio buttons only allow one active value. + + Example: + choices = {"option1": "Option 1", "option2": "Option 2", "option3": "Option 3"} + selected_options = ["option1", "option3"] + checkbox_group_html = checkbox_group( + "group1", + "Select Options", + choices, + selected = selected_options, + type = "radio" + ) + print(checkbox_group_html) + + """ if isinstance(choices, list): choices = {choice: choice for choice in choices} @@ -102,6 +170,36 @@ def update_checkbox( value: Optional[bool] = None, session: Optional[Session] = None, ): + """ + Update a checkbox input widget in a Shiny application session. + + This function updates the properties of a checkbox input widget in a Shiny application + session. It allows modifying the label and value properties of the checkbox, facilitating + dynamic updates to the widget's appearance and state during the Shiny app's execution. + + Args: + id (str): The unique identifier of the checkbox input widget to be updated. + label (str, optional): New label text for the checkbox. If not provided, + the label remains unchanged. + value (bool, optional): New value for the checkbox (True or False). + If not provided, the value remains unchanged. + session (Session, optional): The Shiny application session to which + the checkbox belongs. If not provided, + an active session is required and will be obtained. + + Returns: + None + + Example: + # Assuming 'checkbox_id' is the identifier of the checkbox in the Shiny app + update_checkbox( + checkbox_id, + label = "Updated Label", + value = True, + session = my_session + ) + + """ session = require_active_session(session) msg = {"label": label, "value": value} session.send_input_message(id, drop_none(msg)) @@ -115,6 +213,43 @@ def update_checkbox_group( group_label: Optional[str] = None, session: Optional[Session] = None, ): + """ + Update a checkbox group input element in a Shiny app session. + + This function sends an input message to update the state of a checkbox group + input element identified by its 'id' in a Shiny app session. The 'labels' argument + provides the text labels for the checkboxes, the 'values' argument provides the + corresponding boolean values indicating whether each checkbox is checked or not, + and 'group_label' is an optional label for the entire group of checkboxes. + + Args: + id (str): The identifier of the checkbox group input element. + labels (List[str], optional): List of text labels for the checkboxes. + Default is None. + values (List[bool], optional): List of boolean values indicating checkbox states. + Default is None. + group_label (str, optional): Optional label for the entire group of checkboxes. + Default is None. + session (Session, optional): The Shiny app session to which the update + message will be sent. If not provided, an active session is required. + Default is None. + + Returns: + None + + Example: + # Assume 'my_session' is an active Shiny app session. + checkbox_labels = ["Option 1", "Option 2", "Option 3"] + checkbox_values = [True, False, True] + update_checkbox_group( + id = "my_checkbox_group", + labels = checkbox_labels, + values = checkbox_values, + group_label = "Select Options", + session = my_session, + ) + + """ session = require_active_session(session) msg = {"labels": labels, "values": values, "group_label": group_label} session.send_input_message(id, drop_none(msg)) diff --git a/shiny_semantic/modules/dropdown.py b/shiny_semantic/modules/dropdown.py index 7619f48..bdd0161 100644 --- a/shiny_semantic/modules/dropdown.py +++ b/shiny_semantic/modules/dropdown.py @@ -18,6 +18,39 @@ def dropdown( settings: Optional[dict] = None, class_: Optional[str] = None, ): + """ + Generate a dropdown input component with customizable options. + + This function creates a dropdown input component based on Fomantic UI framework. + The dropdown can be configured with various attributes like ID, available choices, + selected value, placeholder, settings, and additional classes. + + Args: + id (str): Identifier for the dropdown component. Should be unique within the page. + choices (list[str]): List of string choices that populate the dropdown menu. + value (Optional[Union[str, list[str]]], optional): Initially selected value(s). + If a list of values is provided, they will be joined using commas. + placeholder (Optional[str], optional): Placeholder text displayed when no item is selected. + settings (Optional[dict], optional): Additional settings to configure the dropdown behavior. + class_ (Optional[str], optional): Additional CSS class names to apply to the dropdown. + + Returns: + str: A string representing the generated HTML for the dropdown component. + + Example: + choices = ["Option 1", "Option 2", "Option 3"] + settings = {"onChange": "handle_dropdown_change"} + dropdown_html = dropdown( + "myDropdown", + choices, + value = "Option 2", + placeholder = "Select an option", + settings = settings, + class_ = "custom-dropdown" + ) + print(dropdown_html) + + """ choice_tags = [ tags.div( choice, @@ -57,6 +90,38 @@ def input_select( settings: Optional[dict] = None, class_: Optional[str] = None, ): + """ + Generate an input select field with optional label and dropdown choices. + + This function generates an HTML input select field, commonly used for creating dropdown menus, + with an optional label and specified choices. It returns the corresponding HTML representation + of the input field. + + Args: + id (str): Identifier for the input select field. Used to uniquely identify the field and its label. + label (str, optional): Label for the input select field. If provided, it will be associated with the input field. + choices (list[str]): List of strings representing the available options for the dropdown menu. + selected (Union[str, list[str]], optional): Default selected option(s) in the dropdown. Can be a single option or a list of options. + placeholder (str, optional): Placeholder text to display in the dropdown before a selection is made. + settings (dict, optional): Additional settings to customize the behavior and appearance of the dropdown. + class_ (str, optional): CSS class to apply to the input select field. + + Returns: + str: A string representing the HTML representation of the input select field. + + Example: + select_field = input_select( + id = "color-select", + label = "Select a Color", + choices = ["Red", "Green", "Blue"], + selected = "Green", + placeholder = "Choose a color...", + settings = {"searchable": True}, + class_ = "custom-select-field", + ) + print(select_field) + + """ id = resolve_id(id) return tags.div( tags.div( @@ -85,6 +150,37 @@ def update_select( selected: Optional[Union[str, list[str]]] = None, session: Optional[Session] = None, ): + """ + Update a select input in a session with new properties. + + This function is used to update the properties of a select input in a specified session. It allows modifying + the label, available choices, and the selected option of the select input. The updated properties are sent to + the session using the provided `Session` instance. + + Args: + id (str): The unique identifier of the select input to be updated. + label (str, optional): The label text to be displayed alongside the select input. Defaults to None. + choices (list[str], optional): List of available choices for the select input. Defaults to None. + selected (Union[str, list[str]], optional): The option(s) that should be selected in the select input. + It can be a single value or a list of values. Defaults to None. + session (Session, optional): The active session where the select input should be updated. + If not provided, the function will attempt to use the currently active session. + Defaults to None. + + Returns: + None + + Example: + session = create_session() + update_select( + id = "color_select", + label = "Choose a color:", + choices = ["Red", "Green", "Blue"], + selected = "Green", + session = session, + ) + + """ session = require_active_session(session) msg_choices = None diff --git a/shiny_semantic/modules/modal.py b/shiny_semantic/modules/modal.py index a4fd46b..986ca89 100644 --- a/shiny_semantic/modules/modal.py +++ b/shiny_semantic/modules/modal.py @@ -18,6 +18,36 @@ def modal( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate a modal dialog HTML element. + + This function creates a modal dialog element typically used in web applications to display + additional content, alerts, or prompts on top of the main content. The modal consists of a + header, content, and optional actions. + + Args: + id (str): Identifier for the modal element. + header (TagChildArg): HTML content for the modal header. + content (TagChildArg): HTML content for the modal body. + actions (Optional[TagChildArg], optional): HTML content for the modal actions section. + Defaults to None. If not provided, default "Cancel" and "OK" buttons will be included. + class_ (Optional[str], optional): Additional CSS classes to be applied to the modal element. + **kwargs (TagAttrArg): Additional HTML attributes to be applied to the modal element. + + Returns: + str: A string representing the generated modal dialog HTML element. + + Example: + modal_element = modal( + id = "my-modal", + header = tags.h2("Modal Header"), + content = tags.p("Modal content goes here."), + actions = tags.button("confirm", "Confirm", class_ = "positive"), + class_ = "custom-modal", + style = "width: 400px;", + ) + print(modal_element) + """ modal_header = tags.div(header, class_="header") modal_content = tags.div(content, class_="content") modal_actions = ( @@ -50,6 +80,29 @@ async def modal_show( shiny_input: str = "modal", session: Optional[Session] = None, ): + """ + Display a semantic modal dialog in a Shiny app. + + This asynchronous function sends a custom message to the active Shiny session to + display a modal dialog with the provided UI content and optional properties. + + Args: + modal_ui (Tag): The HTML content representing the UI of the modal dialog. + modal_props (dict, optional): Optional properties to customize the modal behavior. + Default is None. + shiny_input (str, optional): The Shiny input identifier for the modal dialog. + Default is "modal". + session (Session, optional): The Shiny session object. If not provided, + the function will attempt to obtain the active session. + + Returns: + None + + Example: + modal_content = tags.div(tags.h2("Modal Title"), tags.p("Modal content goes here.")) + modal_show(modal_content, modal_props = {"size": "large"}) + + """ session = require_active_session(session) await session.send_custom_message( @@ -63,6 +116,27 @@ async def modal_show( def _assert_modal_actions(actions_ui: Tag): + """ + Assert the presence of specific button classes in a modal's action UI. + + This function checks if a provided Tag containing modal action UI has at least one button + with the required classes: 'approve', 'positive', 'deny', or 'negative'. If none of these + classes are found, an Exception is raised. + + Args: + actions_ui (Tag): Tag containing the HTML representation of modal action UI. + + Raises: + Exception: If none of the required button classes are found in the provided Tag. + + Example: + actions = tags.div( + tags.button("Approve", class_ = "approve"), + tags.button("Cancel", class_ = "negative") + ) + _assert_modal_actions(actions) + + """ match_approve = re.search("", str(actions_ui)) match_positive = re.search("", str(actions_ui)) match_deny = re.search("", str(actions_ui)) diff --git a/shiny_semantic/modules/slider.py b/shiny_semantic/modules/slider.py index 411bf81..c09879b 100644 --- a/shiny_semantic/modules/slider.py +++ b/shiny_semantic/modules/slider.py @@ -24,8 +24,45 @@ def slider( **kwargs: TagAttrArg, ): """ - By default, single-value slider is created. - If `end_value` is passed, then the range-value slider is created. + Generate an interactive slider element in HTML. + + This function generates an HTML div element representing an interactive slider. The slider + can be used to select a single value or a range of values, depending on the parameters provided. + The appearance of the slider, including labels and ticks, can be customized through the function + arguments. + + Args: + id (str): Unique identifier for the slider element. + label (str): Label text to describe the purpose of the slider. + min_value (Union[float, int]): The minimum value of the slider. + max_value (Union[float, int]): The maximum value of the slider. + start_value (Union[float, int]): The initial value of the slider. + end_value (Optional[Union[float, int]], optional): The end value for a range slider. + step (Optional[Union[float, int]], optional): The step value for the slider. + show_labels (bool, optional): Whether to show labels for slider values (default is True). + show_ticks (bool, optional): Whether to show ticks for slider values (default is False). + custom_labels (Optional[list[str]], optional): Custom labels for specific values. + class_ (Optional[str], optional): Additional CSS classes for styling the slider div. + **kwargs (TagAttrArg): Additional keyword arguments for HTML attributes. + + Returns: + str: A string representing the generated HTML div element for the slider. + + Example: + slider_element = slider( + id = "my-slider", + label = "Select a value:", + min_value = 0, + max_value = 100, + start_value = 50, + step = 5, + show_labels = True, + show_ticks = True, + custom_labels = ["Low", "Medium", "High"], + class_ = "custom-slider", + ) + print(slider_element) + """ class_ = class_ or "" @@ -58,6 +95,29 @@ def update_slider( value: Union[int, float, list[float], list[int]], session: Optional[Session] = None, ): + """ + Update the value of a slider widget in a session. + + This function is used to update the value of a slider widget identified by its ID + in a session. The new value can be a single integer or float, or a list of integers + or floats, depending on the slider configuration. + + Args: + id (str): The ID of the slider widget to be updated. + value (Union[int, float, list[float], list[int]]): The new value(s) for the slider. + If a single value is provided, it will be converted to a list. + session (Optional[Session], optional): The session object in which the slider exists. + If not provided, an active session is required. + + Returns: + None + + Example: + # Assuming 'my_session' is a valid session object and 'slider_id' is the ID of the slider to update + new_value = 25 + update_slider(slider_id, value = new_value, session = my_session) + + """ if isinstance(value, (int, float)): value = [value] diff --git a/shiny_semantic/page.py b/shiny_semantic/page.py index 8da5269..eb4a32f 100644 --- a/shiny_semantic/page.py +++ b/shiny_semantic/page.py @@ -2,6 +2,27 @@ def page_semantic(*args, title=None, lang="en"): + """ + Generate a HTML page with semantic structure. + + This function takes a variable number of content elements and generates an HTML page + with a predefined semantic structure. The page includes a title, necessary dependencies, + and the provided content elements within the tag. + + Args: + *args: Variable number of content elements to be included in the of the page. + title (str, optional): Title of the HTML page. If not provided, default title "Semantic App" is used. + lang (str, optional): Language attribute for the HTML tag. Defaults to "en" (English). + + Returns: + str: A string representing the generated HTML page. + + Example: + content = TagList(tags.p("Welcome to the Shiny Semantic!"), tags.div(tags.p("Content goes here."))) + html_page = page_semantic(content, title="My Shiny Semantic Page", lang="en") + print(html_page) + + """ title = title or "Semantic App" head = TagList( tags.title(title), @@ -18,6 +39,20 @@ def page_semantic(*args, title=None, lang="en"): def _semantic_dependency(): + """ + Generate a HTMLDependency for Semantic UI. + + This function creates an HTMLDependency object representing the necessary + dependencies for using Semantic UI in a web application. + + Returns: + HTMLDependency: An object containing the necessary scripts and stylesheets for Semantic UI. + + Example: + semantic_dep = _semantic_dependency() + # Use the dependency object appropriately in your application's context. + + """ return HTMLDependency( name="semantic-ui", version="2.9.0", @@ -28,6 +63,21 @@ def _semantic_dependency(): def _shiny_semantic_bindings(): + """ + Generate HTML dependency for Shiny Semantic Bindings. + + This function generates an HTMLDependency object that represents the necessary + bindings for integrating Shiny with Semantic UI components. The dependency includes + the JavaScript source file for the bindings. + + Returns: + HTMLDependency: An HTMLDependency object containing the Shiny Semantic Bindings. + + Example: + semantic_bindings = _shiny_semantic_bindings() + # Use the 'semantic_bindings' object as needed within your code. + + """ return HTMLDependency( name="shiny-semantic-bindings", version="0.0.1", diff --git a/shiny_semantic/views/statistic.py b/shiny_semantic/views/statistic.py index 0a4f591..61653c2 100644 --- a/shiny_semantic/views/statistic.py +++ b/shiny_semantic/views/statistic.py @@ -13,6 +13,41 @@ def statistic( class_: Optional[str] = None, **kwargs: TagAttrArg, ): + """ + Generate a statistic element with a value and label. + + This function creates an HTML statistic element with a provided + value and label. The statistic element + is structured as a container consisting of a value and label, + which can be arranged in different orders. + + Args: + value (TagChildArg): The HTML content representing the value + to be displayed in the statistic. + label (str): The label associated with the value, + providing context or description. + value_first (bool, optional): If True, + the value is displayed above the label. If False, + the label is displayed above the value. Defaults to True. + class_ (str, optional): Additional CSS class(es) to be added + to the statistic element. + **kwargs (TagAttrArg): Additional HTML attributes to be included + in the
tag. + + Returns: + str: A string representing the generated HTML statistic element. + + Example: + value_content = tags.span("42", class_ = "value-content") + stat_element = statistic( + value_content, + label = "Total Items", + value_first = False, + class_ = "highlight" + ) + print(stat_element) + + """ value_element = tags.div(value, class_="value") label_element = tags.div(label, class_="label")