webwidgets 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

webwidgets/__init__.py

@@ -10,7 +10,7 @@
 #
 # =======================================================================
 
-__version__ = "1.0.0"  # Dynamically set by build backend
+__version__ = "1.1.0"  # Dynamically set by build backend
 
 from . import compilation
 from . import utility

webwidgets/compilation/css/__init__.py

@@ -10,5 +10,6 @@
 #
 # =======================================================================
 
-from .css import compile_css, CSSRule, CompiledCSS, apply_css, \
-    default_rule_namer
+from .css import apply_css, compile_css, CompiledCSS, default_class_namer
+from .css_rule import ClassRule, CSSRule
+from . import sections

webwidgets/compilation/css/css.py

@@ -10,88 +10,102 @@
 #
 # =======================================================================
 
+from .css_rule import ClassRule
 import itertools
+from .sections.preamble import Preamble
+from .sections.rule_section import RuleSection
 from typing import Callable, Dict, List, Union
 from webwidgets.compilation.html.html_node import HTMLNode
-from webwidgets.utility.indentation import get_indentation
 from webwidgets.utility.representation import ReprMixin
-from webwidgets.utility.validation import validate_css_identifier
-
-
-class CSSRule(ReprMixin):
-    """A rule in a style sheet.
-    """
-
-    def __init__(self, name: str, declarations: Dict[str, str]):
-        """Stores the name and declarations of the rule.
-
-        :param name: The name of the rule.
-        :type name: str
-        :param declarations: The CSS declarations for the rule, specified as a
-            dictionary where keys are property names and values are their
-            corresponding values. For example: `{'color': 'red'}`
-        :type declarations: Dict[str, str]
-        """
-        super().__init__()
-        self.name = name
-        self.declarations = declarations
 
 
 class CompiledCSS(ReprMixin):
     """A utility class to hold compiled CSS rules.
     """
 
-    def __init__(self, trees: List[HTMLNode], rules: List[CSSRule],
-                 mapping: Dict[int, List[CSSRule]]):
-        """Stores compiled CSS rules.
+    def __init__(self, trees: List[HTMLNode], core: RuleSection,
+                 mapping: Dict[int, List[ClassRule]]):
+        """Stores compiled CSS rules and their mapping to the nodes in the
+        given trees.
 
         :param trees: The HTML trees at the origin of the compilation. These
             are the elements that have been styled with CSS properties.
         :type trees: List[HTMLNode]
-        :param rules: The compiled CSS rules.
-        :type rules: List[CSSRule]
+        :param rules: The CSS section containing the compiled CSS rules.
+        :type rules: RuleSection
         :param mapping: A dictionary mapping each node ID to a list of rules
             that achieve the same style.
-        :type mapping: Dict[int, List[CSSRule]]
+        :type mapping: Dict[int, List[ClassRule]]
         """
         super().__init__()
         self.trees = trees
-        self.rules = rules
+        self.preamble = Preamble()
+        self.core = core
         self.mapping = mapping
 
     def to_css(self, indent_size: int = 4) -> str:
-        """Converts the `rules` dictionary of the :py:class:`CompiledCSS`
-        object into CSS code.
+        """Converts the `preamble` and `core` sections of the
+        :py:class:`CompiledCSS` object into CSS code.
 
-        Rule names are converted to class selectors. Note that each rule and
-        property name is validated with :py:func:`validate_css_identifier`
-        before being converted. 
+        Sections are converted with their :py:meth:`RuleSection.to_css`
+        methods.
 
-        :param indent_size: The number of spaces to use for indentation in the
-            CSS code. Defaults to 4.
+        :param indent_size: See :py:meth:`RuleSection.to_css`.
         :type indent_size: int
         :return: The CSS code as a string.
         :rtype: str
         """
-        # Initializing code and defining indentation
-        css_code = ""
-        indentation = get_indentation(level=1, size=indent_size)
+        return '\n\n'.join(
+            section.to_css(indent_size=indent_size) for section in (
+                self.preamble, self.core
+            ))
 
-        # Writing down each rule
-        for i, rule in enumerate(self.rules):
-            validate_css_identifier(rule.name)
-            css_code += f".{rule.name}" + " {\n"
-            for property_name, value in rule.declarations.items():
-                validate_css_identifier(property_name)
-                css_code += f"{indentation}{property_name}: {value};\n"
-            css_code += "}" + ('\n\n' if i < len(self.rules) - 1 else '')
 
-        return css_code
+def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
+    """Applies the CSS rules to the given tree.
+
+    Rules are added as HTML classes to each node with a style in the tree. If a
+    node does not have a `class` attribute yet, it will be created for that
+    node. Nodes that do not have any style are left untouched.
+
+    Note that this function is recursive and calls itself on each child node of
+    the tree.
+
+    :param css: The compiled CSS object containing the rules to apply and the
+        mapping to each node. It should have been created by invoking
+        :py:func:`compile_css` on the given tree, but it can be modified before
+        passing it to this function, as long as its content remains consistent.
+    :type css: CompiledCSS
+    :param tree: The tree to which the CSS rules should be applied. It will be
+        modified in place by this function. If you want to keep the original
+        tree unchanged, make a deep copy of it using its
+        :py:meth:`HTMLNode.copy` method and pass this copy instead.
+    :type tree: HTMLNode
+    """
+    # Only modifying nodes if they have a style (and therefore if the list of
+    # rules mapped to them in `css.mapping` is not empty)
+    if tree.style:
+
+        # Listing rules to add as classes. We do not add rules that are already
+        # there.
+        rules_to_add = [r.name for r in css.mapping[id(tree)] if r.name not in
+                        tree.attributes.get('class', '').split(' ')]
+
+        # Updating the class attribute. If it already exists and is not empty,
+        # we need to insert a space before adding the CSS classes.
+        maybe_space = ' ' if tree.attributes.get(
+            'class', None) and rules_to_add else ''
+        tree.attributes['class'] = tree.attributes.get(
+            'class', '') + maybe_space + ' '.join(rules_to_add)
+
+    # Recursively applying the CSS rules to all child nodes of the tree
+    for child in tree.children:
+        apply_css(css, child)
 
 
 def compile_css(trees: Union[HTMLNode, List[HTMLNode]],
-                rule_namer: Callable[[List[CSSRule], int],
-                                     str] = None) -> CompiledCSS:
+                class_namer: Callable[[List[ClassRule], int],
+                                      str] = None) -> CompiledCSS:
     """Computes optimized CSS rules from the given HTML trees.
 
     The main purpose of this function is to reduce the number of CSS rules
@@ -118,36 +132,44 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]],
     .. code-block:: python
 
         >>> compiled_css = compile_css(tree)
-        >>> print(compiled_css.rules)
+        >>> print(compiled_css.core.rules)
         [
-            CSSRule(name='r0', declarations={'color': 'blue'}),
-            CSSRule(name='r1', declarations={'margin': '0'}),
-            CSSRule(name='r2', declarations={'padding': '0'})
+            ClassRule(selector='.c0', declarations={'color': 'blue'}, ...),
+            ClassRule(selector='.c1', declarations={'margin': '0'}, ...),
+            ClassRule(selector='.c2', declarations={'padding': '0'}, ...)
         ]
 
+    Internally, each optimized rule gets compiled into a :py:class:`ClassRule`
+    object, which represents a CSS rule whose selector targets the HTML `class`
+    attribute. Each rule gets assigned a unique HTML class and all classes can
+    then be added to the trees with :py:func:`apply_css`. Classes are named
+    `"c0"`, `"c1"`, and so on by default, but this naming process can be
+    customized using the `class_namer` argument.
+
     :param trees: A single tree or a list of trees to optimize over. All
         children are recursively included in the compilation.
     :type trees: Union[HTMLNode, List[HTMLNode]]
-    :param rule_namer: A callable that takes two arguments, which are the list
+    :param class_namer: A callable that takes two arguments, which are the list
         of all compiled rules and an index within that list, and returns a
-        unique name for the rule at the given index.
-
-        This argument allows to customize the rule naming process and use names
-        other than the default `"r0"`, `"r1"`, etc. For example, it can be used
-        to achieve something similar to Tailwind CSS and name rules according
-        to what they achieve, e.g. by prefixing their name with `"m"` for
-        margin rules or `"p"` for padding rules. Note that all rule names will
-        be validated with the :py:func:`validate_css_identifier` function
-        before being written into CSS code.
-
-        Defaults to the :py:func:`default_rule_namer` function which implements
-        a default naming strategy where each rule is named `"r{i}"` where `i`
-        is the index of the rule in the list.
-    :type rule_namer: Callable[[List[CSSRule], int], str]
+        unique name for the HTML class to associate with the rule at the given
+        index.
+
+        This argument allows to customize the class naming process and use names
+        other than the default `"c0"`, `"c1"`, etc. For example, it can be used
+        to achieve something similar to Tailwind CSS and name HTML classes
+        according to what they achieve, e.g. by prefixing their name with `"m"`
+        for margin rules or `"p"` for padding rules. Note that all class
+        selectors will be validated with the :py:func:`validate_css_selector`
+        function before being written into CSS code.
+
+        Defaults to the :py:func:`default_class_namer` function which
+        implements a default naming strategy where each class is named `"c{i}"`
+        where `i` is the index of the rule in the list.
+    :type class_namer: Callable[[List[ClassRule], int], str]
     :return: The :py:class:`CompiledCSS` object containing the optimized rules.
         Every HTML node present in one or more of the input trees is included
         in the :py:attr:`CompiledCSS.mapping` attribute, even if the node does
-        not have a style. Rules are alphabetically ordered by name in the
+        not have a style. Rules are alphabetically ordered by class name in the
         mapping.
     :rtype: CompiledCSS
     """
@@ -155,76 +177,37 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]],
     if isinstance(trees, HTMLNode):
         trees = [trees]
 
-    # Handling default rule_namer
-    rule_namer = default_rule_namer if rule_namer is None else rule_namer
+    # Handling default class_namer
+    class_namer = default_class_namer if class_namer is None else class_namer
 
     # We compute a simple mapping where each CSS property defines its own
     # ruleset
     styles = {k: v for tree in trees for k, v in tree.get_styles().items()}
     properties = set(itertools.chain.from_iterable(s.items()
                      for s in styles.values()))
-    rules = [CSSRule(None, dict([p]))  # Initializing with no name
+    rules = [ClassRule("", dict([p]))  # Initializing with empty name
              for p in sorted(properties)]
     for i, rule in enumerate(rules):  # Assigning name from callback
-        rule.name = rule_namer(rules, i)
+        rule.name = class_namer(rules, i)
     rules = sorted(rules, key=lambda r: r.name)  # Sorting by name
     mapping = {node_id: [r for r in rules if
                          set(r.declarations.items()).issubset(style.items())]
                for node_id, style in styles.items()}
-    return CompiledCSS(trees, rules, mapping)
-
-
-def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
-    """Applies the CSS rules to the given tree.
-
-    Rules are added as HTML classes to each node with a style in the tree. If a
-    node does not have a `class` attribute yet, it will be created for that
-    node. Nodes that do not have any style are left untouched.
-
-    Note that this function is recursive and calls itself on each child node of
-    the tree.
-
-    :param css: The compiled CSS object containing the rules to apply and the
-        mapping to each node. It should have been created by invoking
-        :py:func:`compile_css` on the given tree, but it can be modified before
-        passing it to this function, as long as its content remains consistent.
-    :type css: CompiledCSS
-    :param tree: The tree to which the CSS rules should be applied. It will be
-        modified in place by this function. If you want to keep the original
-        tree unchanged, make a deep copy of it using its
-        :py:meth:`HTMLNode.copy` method and pass this copy instead.
-    :type tree: HTMLNode
-    """
-    # Only modifying nodes if they have a style (and therefore if the list of
-    # rules mapped to them in `css.mapping` is not empty)
-    if tree.style:
-
-        # Listing rules to add as classes. We do not add rules that are already
-        # there.
-        rules_to_add = [r.name for r in css.mapping[id(tree)] if r.name not in
-                        tree.attributes.get('class', '').split(' ')]
 
-        # Updating the class attribute. If it already exists and is not empty,
-        # we need to insert a space before adding the CSS classes.
-        maybe_space = ' ' if tree.attributes.get(
-            'class', None) and rules_to_add else ''
-        tree.attributes['class'] = tree.attributes.get(
-            'class', '') + maybe_space + ' '.join(rules_to_add)
-
-    # Recursively applying the CSS rules to all child nodes of the tree
-    for child in tree.children:
-        apply_css(css, child)
+    # Packaging the results into a CompiledCSS object
+    core = RuleSection(rules=rules, title="Core")
+    return CompiledCSS(trees, core, mapping)
 
 
-def default_rule_namer(rules: List[CSSRule], index: int) -> str:
-    """Default rule naming function. Returns a string like "r{i}" where {i} is
+def default_class_namer(rules: List[ClassRule], index: int) -> str:
+    """Default class naming function. Returns a string like "c{i}" where {i} is
     the index of the rule.
 
-    :param rules: List of all compiled CSSRule objects. This argument is not
+    :param rules: List of all compiled ClassRule objects. This argument is not
         used in this function, but it can be used in other naming strategies.
-    :type rules: List[CSSRule]
-    :param index: Index of the rule being named.
+    :type rules: List[ClassRule]
+    :param index: Index of the rule whose class is being named.
     :type index: int
-    :return: A string like `"r{i}"` where `i` is the index of the rule.
+    :return: A string like `"c{i}"` where `i` is the index of the rule.
     """
-    return f'r{index}'
+    return f'c{index}'

webwidgets/compilation/css/css_rule.py

@@ -0,0 +1,104 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from typing import Dict
+from webwidgets.utility.indentation import get_indentation
+from webwidgets.utility.representation import ReprMixin
+from webwidgets.utility.validation import validate_css_identifier, validate_css_selector
+
+
+class CSSRule(ReprMixin):
+    """A rule in a style sheet.
+    """
+
+    def __init__(self, selector: str, declarations: Dict[str, str]):
+        """Stores the selector and declarations of the rule.
+
+        :param selector: The selector of the rule.
+        :type selector: str
+        :param declarations: The CSS declarations for the rule, specified as a
+            dictionary where keys are property names and values are their
+            corresponding values. For example: `{'color': 'red'}`
+        :type declarations: Dict[str, str]
+        """
+        super().__init__()
+        self.selector = selector
+        self.declarations = declarations
+
+    def to_css(self, indent_size: int = 4) -> str:
+        """Converts the rule into CSS code.
+
+        The rule's name is converted to a class selector.
+
+        Note that the rule's name and all property names are validated before
+        being converted. The rule's name is validated with
+        :py:func:`validate_css_selector` while the property names are validated
+        with :py:func:`validate_css_identifier`. 
+
+        :param indent_size: The number of spaces to use for indentation in the
+            CSS code. Defaults to 4.
+        :type indent_size: int
+        :return: The CSS code as a string.
+        :rtype: str
+        """
+        # Defining indentation
+        indentation = get_indentation(level=1, size=indent_size)
+
+        # Validating the selector
+        validate_css_selector(self.selector)
+
+        # Writing down each property
+        css_code = self.selector + " {\n"
+        for property_name, value in self.declarations.items():
+            validate_css_identifier(property_name)
+            css_code += f"{indentation}{property_name}: {value};\n"
+        css_code += "}"
+
+        return css_code
+
+
+class ClassRule(CSSRule):
+    """A CSS rule that targets a CSS class.
+
+    The class dynamically sets its selector based on its class name.
+    """
+
+    def __init__(self, name: str, declarations: Dict[str, str]):
+        """Creates a new CSS class rule.
+
+        :param name: The name of the CSS class.
+        :type name: str
+        :param declarations: See :py:meth:`CSSRule.__init__`.
+        :type declarations: Dict[str, str]
+        """
+        super().__init__(None, declarations)  # Starting without a selector
+        self._name = None  # Starting without a name
+        self.name = name  # Setting both the selector and the name here
+
+    @property
+    def name(self) -> str:
+        """Returns the name of the CSS class.
+
+        :return: The name of the CSS class.
+        :rtype: str
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: str) -> None:
+        """Sets the name of the CSS class.
+
+        :param value: The new name of the CSS class.
+        :type value: str
+        """
+        self._name = value
+        self.selector = f".{value}"  # Updating the selector

webwidgets/compilation/css/sections/__init__.py

@@ -0,0 +1,14 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .preamble import Preamble
+from .rule_section import RuleSection

webwidgets/compilation/css/sections/css_section.py

@@ -0,0 +1,106 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from abc import ABC, abstractmethod
+from typing import Any
+from webwidgets.utility.representation import ReprMixin
+from webwidgets.utility.validation import validate_css_comment
+
+
+class CSSSection(ABC, ReprMixin):
+    """Abstract base class representing a section of a CSS file.
+
+    All subclasses of :py:class:`CSSSection` must implement a
+    :py:meth:`compile_content` method that returns a string.
+    """
+
+    @staticmethod
+    def prettify_title(title: str, min_length: int) -> str:
+        """Returns a prettified version of the given title with decorative
+        characters `=` around it.
+
+        This function will add the minimum number of decorative characters to
+        the title while keeping symmetry and remaining over the given minimum
+        length. In particular, if the given title is already above the minimum
+        length, this function will return it as is.
+
+        :param title: The title to prettify.
+        :type title: str
+        :param max_length: The minimum length of the prettified title.
+        :type max_length: int
+        :return: The prettified title.
+        :rtype: str
+        """
+        # If the title is already above min_length, we don't add decorative
+        # characters
+        if len(title) >= min_length:
+            return title
+
+        # Otherwise, we add decorative characters around the title
+        remaining = min_length - len(title)
+        characters = "=" * max(((remaining - 1) // 2), 1)
+        return characters + ' ' + title + ' ' + characters
+
+    def __init__(self, title: str = None):
+        """Creates a new section with an optional title.
+
+        :param title: The title of the section. If provided, the section will
+            be preceded by a comment containing the title in the output CSS
+            code. If None, no title will be used to separate the section from
+            the rest of the code.
+        :type title: str
+        """
+        super().__init__()
+        self.title = title
+
+    @abstractmethod
+    def compile_content(self) -> str:
+        """Converts the content of the CSSSection object (excluding the title)
+        into CSS code.
+
+        This method must be overridden by subclasses to compile specific CSS
+        code.
+        """
+        pass
+
+    def to_css(self, *args: Any, **kwargs: Any) -> str:
+        """Converts the CSSSection object into CSS code.
+
+        If the section has a title, it will be prettified with
+        :py:meth:`CSSSection.prettify_title` and turned into a comment. That
+        comment will be validated with :py:func:`validate_css_comment` and
+        inserted before the result of :py:meth:`CSSSection.compile_content` in
+        the CSS code.
+
+        If the section has no title, this function will produce the same result
+        as :py:meth:`CSSSection.compile_content`.
+
+        :param args: Arguments to pass to
+            :py:meth:`CSSSection.compile_content`.
+        :type args: Any
+        :param kwargs: Keyword arguments to pass to
+            :py:meth:`CSSSection.compile_content`.
+        :type kwargs: Any
+        :return: The CSS code for the section.
+        :rtype: str
+        """
+        # If no title, we just return the compiled content
+        if self.title is None:
+            return self.compile_content(*args, **kwargs)
+
+        # Otherwise, we turn the title into a comment and validate it
+        comment = ' ' + CSSSection.prettify_title(self.title, 40) + ' '
+        validate_css_comment(comment)
+
+        # Adding the comment before the compiled content
+        return "/*" + comment + "*/\n\n" + \
+            self.compile_content(*args, **kwargs)

webwidgets/compilation/css/sections/preamble.py

@@ -0,0 +1,40 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .rule_section import RuleSection
+from webwidgets.compilation.css.css_rule import CSSRule
+
+
+class Preamble(RuleSection):
+    """A set of CSS rules that apply globally to all HTML elements.
+
+    The CSS preamble serves as a global default for multiple properties. It is
+    used to define the document's box model and set all margin and padding
+    values to 0.
+    """
+
+    def __init__(self):
+        """Creates a new CSS preamble."""
+        super().__init__(
+            rules=[
+                CSSRule("*, *::before, *::after", {
+
+                    # Defining the box model to border-box
+                    "box-sizing": "border-box",
+
+                    # Setting all margin and padding values to 0
+                    "margin": "0",
+                    "padding": "0"
+                })
+            ],
+            title="Preamble"
+        )

webwidgets/compilation/css/sections/rule_section.py

@@ -0,0 +1,43 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .css_section import CSSSection
+from typing import List
+from webwidgets.compilation.css.css_rule import CSSRule
+
+
+class RuleSection(CSSSection):
+    """A section containing a set of CSS rules.
+    """
+
+    def __init__(self, rules: List[CSSRule] = None, title: str = None):
+        """Creates a new section with the given rules and title.
+
+        :param rules: A list of CSSRule objects to include in the section.
+        :type rules: List[CSSRule]
+        :param title: The title of the section.
+        :type title: str
+        """
+        super().__init__(title=title)
+        self.rules = [] if rules is None else rules
+
+    def compile_content(self, indent_size: int = 4) -> str:
+        """Compiles the CSS representation of the rules contained in the
+        section.
+
+        :param indent_size: See :py:meth:`CSSRule.to_css`.
+        :type indent_size: int
+        :return: The CSS representation of the rules.
+        :rtype: str
+        """
+        return "\n\n".join([
+            rule.to_css(indent_size=indent_size) for rule in self.rules])

webwidgets/compilation/html/__init__.py

@@ -12,4 +12,4 @@
 
 from .html_node import HTMLNode, no_start_tag, no_end_tag, one_line, RawText, \
     RootNode
-from .html_tags import TextNode
+from .html_tags import *

webwidgets/compilation/html/html_tags.py

@@ -45,6 +45,11 @@ class Body(HTMLNode):
     pass
 
 
+class Div(HTMLNode):
+    """A `<div>` element used for grouping elements."""
+    pass
+
+
 @one_line
 @no_end_tag
 class Doctype(HTMLNode):

webwidgets/utility/validation.py

@@ -14,6 +14,34 @@ from typing import *
 import re
 
 
+# CSS selectors that are considered valid as selectors but not as identifiers
+# according to the `validate_css_identifier()` function.
+SPECIAL_SELECTORS = [
+    "*", "*::before", "*::after"
+]
+
+
+def validate_css_comment(comment: str) -> None:
+    """Validates that the given comment is a valid CSS comment according to the
+    CSS syntax rules and raises an exception if not.
+
+    This function just checks that the comment does not contain any closing
+    sequence `*/` as defined in the CSS Syntax Module Level 3, paragraph 4.3.2
+    (see source: https://www.w3.org/TR/css-syntax-3/#consume-comment).
+
+    :param comment: The CSS comment to validate, without its opening and
+        closing sequences. It can include any number of opening sequences
+        (`/*`) as part of its content, in which case it is still a valid
+        comment per the CSS specification, but it cannot contain any closing
+        sequences (`*/`).
+    :type comment: str
+    :raises ValueError: If the comment is not a valid CSS comment.
+    """
+    if "*/" in comment:
+        raise ValueError(
+            f"Invalid CSS comment: '{comment}' contains closing sequence '*/'")
+
+
 def validate_css_identifier(identifier: str) -> None:
     """Checks if the given identifier is a valid identifier token according to
     the CSS syntax rules and raises an exception if not.
@@ -57,6 +85,45 @@ def validate_css_identifier(identifier: str) -> None:
                          "allowed.")
 
 
+def validate_css_selector(selector: str) -> None:
+    """Checks if the given CSS selector is valid and raises an exception if
+    not.
+
+    To be valid, the selector must either be:
+    - a special selector, which is defined as either `*`, `*::before`, or
+      `*::after`
+    - any combination of special selectors separated by a comma and a single
+      space (e.g. `*::before, *::after`)
+    - or a class selector, which is defined as a dot `.` followed by a valid
+      CSS identifier, as defined and enforced by the
+      :py:func:`validate_css_identifier` function
+
+    Note that this function imposes stricter rules than the official CSS
+    Selector Level 4 specification (see source:
+    https://www.w3.org/TR/selectors-4/). For example, this function does not
+    allow selectors with the relational pseudo-class `:has()` whereas the
+    specification does.
+
+    :param selector: The CSS selector to validate.
+    :type selector: str
+    :raises ValueError: If the selector is not a special selector nor a valid
+        CSS identifier.
+    """
+    # Checking if the selector is a special selector
+    if selector in SPECIAL_SELECTORS:
+        return
+
+    # Checking if the selector is a combination of special selectors
+    if all(part in SPECIAL_SELECTORS for part in selector.split(", ")):
+        return
+
+    # Otherwise, checking if the selector is a class selector
+    if not selector.startswith("."):
+        raise ValueError("Class selector must start with '.' but got: "
+                         f"{selector}")
+    validate_css_identifier(selector[1:])
+
+
 def validate_html_class(class_attribute: str) -> None:
     """Checks if the given HTML class attribute is valid and raises an
     exception if not.
@@ -65,7 +132,7 @@ def validate_html_class(class_attribute: str) -> None:
     - the class attribute cannot start nor end with a space
     - the class attribute cannot contain double spaces
     - each class in the attribute must be a valid CSS identifier, as validated
-      by the :py:func:`validate_css_identifier` function.
+      by the :py:func:`validate_css_identifier` function
 
     Note that this function imposes stricter rules than rule 2.3.7 of the HTML5
     specification (see source:

webwidgets/website/website.py

@@ -12,7 +12,7 @@
 
 from .compiled_website import CompiledWebsite
 from typing import Any, Callable, List
-from webwidgets.compilation.css import compile_css, CSSRule, apply_css
+from webwidgets.compilation.css import apply_css, compile_css, ClassRule
 from webwidgets.utility.representation import ReprMixin
 from webwidgets.widgets.containers.page import Page
 
@@ -44,7 +44,7 @@ class Website(ReprMixin):
                 force_one_line: bool = False,
                 indent_level: int = 0,
                 indent_size: int = 4,
-                rule_namer: Callable[[List[CSSRule], int], str] = None,
+                class_namer: Callable[[List[ClassRule], int], str] = None,
                 **kwargs: Any) -> CompiledWebsite:
         """Compiles the website into HTML and CSS code.
 
@@ -59,8 +59,8 @@ class Website(ReprMixin):
         :param indent_size: See :py:meth:`HTMLNode.to_html` and
             :py:meth:`CompiledCSS.to_css`.
         :type indent_size: int
-        :param rule_namer: See :py:func:`compile_css`.
-        :type rule_namer: Callable[[List[CSSRule], int], str]
+        :param class_namer: See :py:func:`compile_css`.
+        :type class_namer: Callable[[List[ClassRule], int], str]
         :param kwargs: See :py:meth:`HTMLNode.to_html`.
         :type kwargs: Any
         :return: A new :py:class:`CompiledWebsite` object containing the
@@ -72,7 +72,7 @@ class Website(ReprMixin):
                  for page in self.pages]
 
         # Compiling HTML and CSS code
-        compiled_css = compile_css(trees, rule_namer)
+        compiled_css = compile_css(trees, class_namer)
         for tree in trees:
             apply_css(compiled_css, tree)
         html_content = [tree.to_html(

webwidgets/widgets/containers/__init__.py

@@ -10,5 +10,6 @@
 #
 # =======================================================================
 
+from .box import Box, Direction
 from .container import Container
 from .page import Page

webwidgets/widgets/containers/box.py

@@ -0,0 +1,70 @@
+# =======================================================================
+#
+#  This file is part of WebWidgets, a Python package for designing web
+#  UIs.
+#
+#  You should have received a copy of the MIT License along with
+#  WebWidgets. If not, see <https://opensource.org/license/mit>.
+#
+#  Copyright(C) 2025, mlaasri
+#
+# =======================================================================
+
+from .container import Container
+from enum import auto, Enum
+from webwidgets.compilation.html.html_tags import Div
+
+
+class Direction(Enum):
+    HORIZONTAL = auto()
+    VERTICAL = auto()
+
+
+class Box(Container):
+    """A widget that lays out its child widgets inside a row or a column.
+    """
+
+    def __init__(self, direction: Direction):
+        """Creates a new Box with the given direction.
+
+        :param direction: The direction in which the child widgets should be
+            laid out. Can be either `Direction.HORIZONTAL` or
+            `Direction.VERTICAL`.
+        :type direction: Direction
+        """
+        super().__init__()
+        self.direction = direction
+
+    def build(self):
+        """Builds the HTML representation of the Box.
+
+        The box is constructed as a `<div>` element with a flexbox layout. Its
+        `flex-direction` property is set to either "row" or "column" based on
+        the direction parameter, and it has a `data-role` attribute of "box".
+
+        Each child widget is wrapped inside its own `<div>` element with a
+        `data-role` attribute of "box-item". The items are centered within
+        their own `<div>`.
+        """
+        # Building child nodes
+        nodes = [w.build() for w in self.widgets]
+
+        # Building box items that wrap around child nodes
+        items = [Div(
+            children=[node],
+            attributes={"data-role": "box-item"},
+            style={
+                "display": "flex",
+                "flex-direction": "row",
+                "align-items": "center",
+                "justify-content": "center",
+                "flex-grow": "1"
+            }) for node in nodes]
+
+        # Assembling the box
+        flex_dir = "row" if self.direction == Direction.HORIZONTAL else "column"
+        box = Div(children=items, attributes={"data-role": "box"}, style={
+            "display": "flex",
+            "flex-direction": flex_dir
+        })
+        return box

webwidgets/widgets/widget.py

@@ -16,8 +16,7 @@ from webwidgets.utility.representation import ReprMixin
 
 
 class Widget(ABC, ReprMixin):
-    """
-    Abstract base class for all widgets.
+    """Abstract base class for all widgets.
 
     All subclasses of :py:class:`Widget` must implement a :py:meth:`build`
     method that returns an :py:class:`HTMLNode` object.

{webwidgets-1.0.0.dist-info → webwidgets-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: webwidgets
-Version: 1.0.0
+Version: 1.1.0
 Summary: A Python package for designing web UIs.
 Project-URL: Source code, https://github.com/mlaasri/WebWidgets
 Author: mlaasri
@@ -9,6 +9,11 @@ Keywords: design,webui
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: numpy; extra == 'dev'
+Requires-Dist: pillow; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: selenium; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # WebWidgets

webwidgets-1.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+webwidgets/__init__.py,sha256=XGu3i9D0Zs9W12E62C5Yq-Aejh_GTlyz6197FAoxiME,549
+webwidgets/compilation/__init__.py,sha256=hb61nhmPTghIzuA_hun98xT5Ngv7QFAgMHD44g-9uOo,433
+webwidgets/compilation/css/__init__.py,sha256=A4VUGyy92Vn32Km2VuJL5bBmLdovN6PDfv_DctRdzJk,534
+webwidgets/compilation/css/css.py,sha256=d7sxMOfT2s2sxG2O4LB4zSuknDb_fPcikKkiQk70vpc,9299
+webwidgets/compilation/css/css_rule.py,sha256=QkeyVc9hmRwz0QY1avDugBpMM849VXcvJi18-c9h4x4,3530
+webwidgets/compilation/css/sections/__init__.py,sha256=qPLq_w0kIPGvIIXxsblF7iUdm9AOA-CUl06krTMnHHI,465
+webwidgets/compilation/css/sections/css_section.py,sha256=LfQojXSYbsh9UcbqD4vn6heEO7qjGNrwy7Py5bsvy9U,4020
+webwidgets/compilation/css/sections/preamble.py,sha256=DwRwcKrVVeiypsHQn0FIQojpOQ3KUcrlaawxfipCue8,1251
+webwidgets/compilation/css/sections/rule_section.py,sha256=BBeIJyVRz2ZeBxEC6VrEymXF6LjzE_GPu6X04A-lGF8,1456
+webwidgets/compilation/html/__init__.py,sha256=h8eWh8BbjLZA1wIGAeOxyhZIUM1e36ZgMTwL5SQajHc,514
+webwidgets/compilation/html/html_node.py,sha256=lOf1LEoVx23teWHfdlt5IpSv14cE6EI-aDyFGC_BXSU,11697
+webwidgets/compilation/html/html_tags.py,sha256=R13axcPAOnqRVPM8FP0k04QIW7gZMSJt3jlsv7Q-fXg,2276
+webwidgets/utility/__init__.py,sha256=Sl-dzpPPTHykkmLSfobhqHmlzUSPtvhaR4xtJy_tiOg,505
+webwidgets/utility/indentation.py,sha256=BaOQRqWdG7T5k_g1-ia9jewPFZjD3afjZH_Fc4NSVwo,906
+webwidgets/utility/representation.py,sha256=lQ15v_DZOHBQKLM8pzRE1tuJkU_modhPTpWpSJ2lBCE,1061
+webwidgets/utility/sanitizing.py,sha256=OKJRDqk-OXYCWeK6ie3GdfQvb49wTs93kd971mg5oK0,5770
+webwidgets/utility/validation.py,sha256=RB3JvMcVP6AKP1yrl44kFUQRzswtMa6ql7r2tqvrojE,6989
+webwidgets/website/__init__.py,sha256=zp4N3CtY0SLNfDV9p2Y0tqbta-vFOX1PSJr7eQ9rQdk,471
+webwidgets/website/compiled_website.py,sha256=lR_sabYtdWiRWicyxEFs4yxRUB_TbMowpsNz3CtqQBQ,1129
+webwidgets/website/website.py,sha256=2vdIxYLXOu_otiF-KTOBigoic0aUWwgglfXAAZRzURg,3349
+webwidgets/widgets/__init__.py,sha256=J2br7F-16URKvWshkJcc4nth27YQsaLrdVZu0xXx5CU,449
+webwidgets/widgets/widget.py,sha256=NRyiy_vBStX2r-LBeJpqFy-AMw1aaqxrx4sz-GIdJnE,1034
+webwidgets/widgets/containers/__init__.py,sha256=bKhkQHUfBMjYi7f0lPSBwP2EMn_M7n9VIh3He4gRqyc,484
+webwidgets/widgets/containers/box.py,sha256=L5qYFsHWs0YzpAZ2Mv_i3pWzMp5od98tLjjf8KpnDhY,2351
+webwidgets/widgets/containers/container.py,sha256=blpO2y9IiZ_4opwe9pqsSJPAZEN1P_ZRK4a27NpnMrg,1158
+webwidgets/widgets/containers/page.py,sha256=sJ8QDmZ_6jzRFt4lyiAEPwjPvDTKm8EWOjz_Tq_cdjU,2180
+webwidgets-1.1.0.dist-info/METADATA,sha256=b4hRl-cnHN3ndE_8RhOZPM_YFNtoJJfn6u8ovtFi8LA,1607
+webwidgets-1.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+webwidgets-1.1.0.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
+webwidgets-1.1.0.dist-info/RECORD,,

webwidgets-1.0.0.dist-info/RECORD

@@ -1,24 +0,0 @@
-webwidgets/__init__.py,sha256=IZAAOuEwU_cC_oy0dJ2WSw9wXnwrLyZ4mqszBPma7MA,549
-webwidgets/compilation/__init__.py,sha256=hb61nhmPTghIzuA_hun98xT5Ngv7QFAgMHD44g-9uOo,433
-webwidgets/compilation/css/__init__.py,sha256=ZisiFaw9RqNuVqewOjnEOLLLZwgjfW95yruMXGRGp_I,484
-webwidgets/compilation/css/css.py,sha256=93WuxY-ADUDK_cBuGS-hUuV4HctZjtaG3cqeoE4S3oQ,9725
-webwidgets/compilation/html/__init__.py,sha256=iupXt6punHDLAFdygshmQeFVOLCeZ8HbwCWclL1FH54,521
-webwidgets/compilation/html/html_node.py,sha256=lOf1LEoVx23teWHfdlt5IpSv14cE6EI-aDyFGC_BXSU,11697
-webwidgets/compilation/html/html_tags.py,sha256=tFc5P6_rqyetFXJKlxt8n_IhBD758LHPql9peU9__6o,2188
-webwidgets/utility/__init__.py,sha256=Sl-dzpPPTHykkmLSfobhqHmlzUSPtvhaR4xtJy_tiOg,505
-webwidgets/utility/indentation.py,sha256=BaOQRqWdG7T5k_g1-ia9jewPFZjD3afjZH_Fc4NSVwo,906
-webwidgets/utility/representation.py,sha256=lQ15v_DZOHBQKLM8pzRE1tuJkU_modhPTpWpSJ2lBCE,1061
-webwidgets/utility/sanitizing.py,sha256=OKJRDqk-OXYCWeK6ie3GdfQvb49wTs93kd971mg5oK0,5770
-webwidgets/utility/validation.py,sha256=bUjpiGP59GW3DPvQ1hwR5ezBMmcSd6v4xlDLwTHZv_A,4261
-webwidgets/website/__init__.py,sha256=zp4N3CtY0SLNfDV9p2Y0tqbta-vFOX1PSJr7eQ9rQdk,471
-webwidgets/website/compiled_website.py,sha256=lR_sabYtdWiRWicyxEFs4yxRUB_TbMowpsNz3CtqQBQ,1129
-webwidgets/website/website.py,sha256=a5Qmm4DOIYMXHoBDyKzB6Ex2kaPFCSPgodF7LAVyrPE,3339
-webwidgets/widgets/__init__.py,sha256=J2br7F-16URKvWshkJcc4nth27YQsaLrdVZu0xXx5CU,449
-webwidgets/widgets/widget.py,sha256=8ZRcVmmtjQzeA_uGZi10H4XvqgGEtGmr9275FId8zt0,1039
-webwidgets/widgets/containers/__init__.py,sha256=6LPlYaxXiMgC5YPHhi0HLhn7iCeh_5IFY70mv7a-wSA,452
-webwidgets/widgets/containers/container.py,sha256=blpO2y9IiZ_4opwe9pqsSJPAZEN1P_ZRK4a27NpnMrg,1158
-webwidgets/widgets/containers/page.py,sha256=sJ8QDmZ_6jzRFt4lyiAEPwjPvDTKm8EWOjz_Tq_cdjU,2180
-webwidgets-1.0.0.dist-info/METADATA,sha256=DHfGCHdolxBicrkQjAzWGm_B7d_SgY2OnwZ261tSxUk,1434
-webwidgets-1.0.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-webwidgets-1.0.0.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
-webwidgets-1.0.0.dist-info/RECORD,,