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

webwidgets/__init__.py

@@ -10,6 +10,9 @@
 #
 # =======================================================================
 
-__version__ = "0.2.1"  # Dynamically set by build backend
+__version__ = "1.1.0"  # Dynamically set by build backend
 
 from . import compilation
+from . import utility
+from .website import *
+from .widgets import *

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,87 +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.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 = ' ' * 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
@@ -117,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
     """
@@ -154,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
 
-    # For now, we just return a simple mapping where each CSS property defines
-    # its own ruleset
+    # 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

@@ -10,5 +10,6 @@
 #
 # =======================================================================
 
-from .html_node import HTMLNode, no_start_tag, no_end_tag, one_line, RawText
-from .html_tags import TextNode
+from .html_node import HTMLNode, no_start_tag, no_end_tag, one_line, RawText, \
+    RootNode
+from .html_tags import *