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

webwidgets/__init__.py

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

webwidgets/compilation/css/__init__.py

@@ -10,4 +10,5 @@
 #
 # =======================================================================
 
-from .css import compile_css, CompiledCSS, apply_css
+from .css import compile_css, CSSRule, CompiledCSS, apply_css, \
+    default_rule_namer

webwidgets/compilation/css/css.py

@@ -11,31 +11,50 @@
 # =======================================================================
 
 import itertools
-from typing import Dict, List, Union
+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 CompiledCSS:
+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: Dict[str, Dict[str, str]],
-                 mapping: Dict[int, List[str]]):
+    def __init__(self, trees: List[HTMLNode], rules: List[CSSRule],
+                 mapping: Dict[int, List[CSSRule]]):
         """Stores compiled CSS rules.
 
         :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, specified as a dictionary mapping
-            the rule's name to its corresponding CSS declarations. For example:
-            `{'r0': {'color': 'red'}}`.
-        :type rules: Dict[str, Dict[str, str]]
+        :param rules: The compiled CSS rules.
+        :type rules: List[CSSRule]
         :param mapping: A dictionary mapping each node ID to a list of rules
-            that achieve the same style. Rules must be specified by their name.
-            For example: `{123: ['r0', 'r2'], 456: ['r1']}`.
-        :type mapping: Dict[int, List[str]]
+            that achieve the same style.
+        :type mapping: Dict[int, List[CSSRule]]
         """
+        super().__init__()
         self.trees = trees
         self.rules = rules
         self.mapping = mapping
@@ -44,9 +63,9 @@ class CompiledCSS:
         """Converts the `rules` dictionary of the :py:class:`CompiledCSS`
         object into CSS code.
 
-        Each rule name is converted to a class selector and each property name
-        is validated with :py:func:`validate_css_identifier` before being
-        converted.
+        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. 
 
         :param indent_size: The number of spaces to use for indentation in the
             CSS code. Defaults to 4.
@@ -56,12 +75,13 @@ class CompiledCSS:
         """
         # Initializing code and defining indentation
         css_code = ""
-        indentation = ' ' * indent_size
+        indentation = get_indentation(level=1, size=indent_size)
 
-        # Writing down each rule from the rules dictionary
-        for i, (name, declarations) in enumerate(self.rules.items()):
-            css_code += f".{name}" + " {\n"
-            for property_name, value in declarations.items():
+        # 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 '')
@@ -69,7 +89,9 @@ class CompiledCSS:
         return css_code
 
 
-def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
+def compile_css(trees: Union[HTMLNode, List[HTMLNode]],
+                rule_namer: Callable[[List[CSSRule], 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
@@ -97,15 +119,31 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
 
         >>> compiled_css = compile_css(tree)
         >>> print(compiled_css.rules)
-        {
-            'r0': {'color': 'blue'},
-            'r1': {'margin': '0'},
-            'r2': {'padding': '0'}
-        }
+        [
+            CSSRule(name='r0', declarations={'color': 'blue'}),
+            CSSRule(name='r1', declarations={'margin': '0'}),
+            CSSRule(name='r2', declarations={'padding': '0'})
+        ]
 
     :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
+        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]
     :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
@@ -117,14 +155,21 @@ def compile_css(trees: Union[HTMLNode, List[HTMLNode]]) -> CompiledCSS:
     if isinstance(trees, HTMLNode):
         trees = [trees]
 
-    # For now, we just return a simple mapping where each CSS property defines
-    # its own ruleset
+    # Handling default rule_namer
+    rule_namer = default_rule_namer if rule_namer is None else rule_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 = {f"r{i}": dict([p]) for i, p in enumerate(sorted(properties))}
-    mapping = {node_id: sorted([n for n, r in rules.items() if
-                                set(r.items()).issubset(style.items())])
+    rules = [CSSRule(None, dict([p]))  # Initializing with no name
+             for p in sorted(properties)]
+    for i, rule in enumerate(rules):  # Assigning name from callback
+        rule.name = rule_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)
 
@@ -156,7 +201,7 @@ def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
 
         # Listing rules to add as classes. We do not add rules that are already
         # there.
-        rules_to_add = [r for r in css.mapping[id(tree)] if r and r not in
+        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,
@@ -169,3 +214,17 @@ def apply_css(css: CompiledCSS, tree: HTMLNode) -> None:
     # Recursively applying the CSS rules to all child nodes of the tree
     for child in tree.children:
         apply_css(css, child)
+
+
+def default_rule_namer(rules: List[CSSRule], index: int) -> str:
+    """Default rule naming function. Returns a string like "r{i}" where {i} is
+    the index of the rule.
+
+    :param rules: List of all compiled CSSRule 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 index: int
+    :return: A string like `"r{i}"` where `i` is the index of the rule.
+    """
+    return f'r{index}'

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_node import HTMLNode, no_start_tag, no_end_tag, one_line, RawText, \
+    RootNode
 from .html_tags import TextNode

webwidgets/compilation/html/html_node.py

@@ -13,11 +13,13 @@
 import copy
 import itertools
 from typing import Any, Dict, List, Union
+from webwidgets.utility.indentation import get_indentation
+from webwidgets.utility.representation import ReprMixin
 from webwidgets.utility.sanitizing import sanitize_html_text
 from webwidgets.utility.validation import validate_html_class
 
 
-class HTMLNode:
+class HTMLNode(ReprMixin):
     """Represents an HTML node (for example, a div or a span).
     """
 
@@ -34,6 +36,7 @@ class HTMLNode:
         :param style: Dictionary of CSS properties for the node. Defaults to an empty dictionary.
         :type style: Dict[str, str]
         """
+        super().__init__()
         self.children = [] if children is None else children
         self.attributes = {} if attributes is None else attributes
         self.style = {} if style is None else style
@@ -51,11 +54,13 @@ class HTMLNode:
     def _render_attributes(self) -> str:
         """Renders the attributes of the HTML node into a string that can be added to the start tag.
 
+        Attributes are sorted alphabetically by name.
+
         :return: A string containing all attribute key-value pairs separated by spaces.
         :rtype: str
         """
         return ' '.join(
-            f'{key}="{value}"' for key, value in self.attributes.items()
+            f'{k}="{v}"' for k, v in sorted(self.attributes.items())
         )
 
     def add(self, child: 'HTMLNode') -> None:
@@ -134,7 +139,14 @@ class HTMLNode:
         :type collapse_empty: bool
         :param indent_size: The number of spaces to use for each indentation level.
         :type indent_size: int
-        :param indent_level: The current level of indentation in the HTML output.
+        :param indent_level: The current level of indentation in the HTML
+            output.
+
+            This argument supports negative values as a way to flatten the HTML
+            output down to a certain depth with indentation resuming as normal
+            afterwards. If negative, `indent_level` is construed as an offset
+            on the depth in the HTML tree represented by the node, in which
+            case the node will wait for that depth before starting indentation.
         :type indent_level: int
         :param force_one_line: If True, forces all child elements to be rendered on a single line without additional
             indentation. Defaults to False.
@@ -149,7 +161,8 @@ class HTMLNode:
         :rtype: str or List[str]
         """
         # Opening the element
-        indentation = "" if force_one_line else ' ' * indent_size * indent_level
+        indentation = "" if force_one_line else get_indentation(
+            indent_level, indent_size)
         html_lines = [indentation + self.start_tag]
 
         # If content must be in one line
@@ -262,7 +275,34 @@ class RawText(HTMLNode):
         """
         sanitized = sanitize_html_text(
             self.text, replace_all_entities=replace_all_entities)
-        line = ' ' * indent_size * indent_level + sanitized
+        line = get_indentation(indent_level, indent_size) + sanitized
         if return_lines:
             return [line]
         return line
+
+
+@no_start_tag
+@no_end_tag
+class RootNode(HTMLNode):
+    """The root node of an HTML document.
+
+    This is the top-level node that contains all other nodes.
+    """
+
+    def to_html(self, indent_level: int = 0, **kwargs: Any) -> Union[str, List[str]]:
+        """Converts the root node to HTML code.
+
+        This method overrides :py:meth:`HTMLNode.to_html`. The only difference
+        between this method and that of the base class is that the indentation
+        level is adjusted by one level, so the root node acts as an array of
+        elements.
+
+        :param indent_level: See :py:meth:`HTMLNode.to_html`.
+        :type indent_level: int
+        :param kwargs: Other keyword arguments. These are passed to
+            :py:meth:`HTMLNode.to_html`.
+        :type kwargs: Any
+        :return: See :py:meth:`HTMLNode.to_html`.
+        :type return: str or List[str]
+        """
+        return super().to_html(indent_level=indent_level - 1, **kwargs)

webwidgets/compilation/html/html_tags.py

@@ -10,7 +10,7 @@
 #
 # =======================================================================
 
-from .html_node import HTMLNode, one_line, RawText
+from .html_node import HTMLNode, no_end_tag, one_line, RawText
 from typing import Dict
 
 
@@ -38,3 +38,40 @@ class TextNode(HTMLNode):
         super().__init__(children=[
             RawText(text)
         ], attributes=attributes, style=style)
+
+
+class Body(HTMLNode):
+    """The `<body>` element containing the visible content of a document."""
+    pass
+
+
+@one_line
+@no_end_tag
+class Doctype(HTMLNode):
+    """The `<!DOCTYPE html>` doctype declaration of a document."""
+
+    def __init__(self):
+        """Creates a `<!DOCTYPE html>` doctype declaration element."""
+        super().__init__()
+
+    @property
+    def start_tag(self) -> str:
+        """Overrides the start tag for this node."""
+        return "<!DOCTYPE html>"
+
+
+class Head(HTMLNode):
+    """The `<head>` element containing metadata about a document."""
+    pass
+
+
+class Html(HTMLNode):
+    """The `<html>` element of an HTML document."""
+    pass
+
+
+@one_line
+@no_end_tag
+class Link(HTMLNode):
+    """A `<link>` element for linking to external resources."""
+    pass

webwidgets/utility/__init__.py

@@ -10,5 +10,7 @@
 #
 # =======================================================================
 
+from .indentation import *
+from .representation import *
 from .sanitizing import *
 from .validation import *

webwidgets/utility/indentation.py

@@ -0,0 +1,25 @@
+# =======================================================================
+#
+#  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
+#
+# =======================================================================
+
+def get_indentation(level: int, size: int = 4) -> str:
+    """Returns an indentation string for the given level.
+
+    :param level: The level of indentation. If negative, this
+        function will return an empty string representing no indentation.
+    :type level: int
+    :param size: The number of spaces to use for each indentation level.
+        Defaults to 4 spaces.
+    :type size: int
+    :return: A string representing the indentation.
+    :rtype: str
+    """
+    return ' ' * (max(level, 0) * size)

webwidgets/utility/representation.py

@@ -0,0 +1,34 @@
+# =======================================================================
+#
+#  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
+#
+# =======================================================================
+
+class ReprMixin:
+    """A mixin class that is represented with its variables when printed.
+
+    For example:
+
+    >>> class MyClass(RepresentedWithVars):
+    ...     def __init__(self, a, b):
+    ...         self.a = a
+    ...         self.b = b
+    >>> obj = MyClass(1, 2)
+    >>> print(obj)
+    MyClass(a=1, b=2)
+    """
+
+    def __repr__(self) -> str:
+        """Returns a string exposing all member variables of the class.
+
+        :return: A string representing the class with its variables.
+        :rtype: str
+        """
+        variables = ', '.join(f'{k}={repr(v)}' for k, v in vars(self).items())
+        return f"{self.__class__.__name__}({variables})"

webwidgets/website/__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 .compiled_website import CompiledWebsite
+from .website import Website

webwidgets/website/compiled_website.py

@@ -0,0 +1,34 @@
+# =======================================================================
+#
+#  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 List
+from webwidgets.utility.representation import ReprMixin
+
+
+class CompiledWebsite(ReprMixin):
+    """A utility class to store compiled HTML and CSS code obtained from a
+    :py:class:`Website` object.
+    """
+
+    def __init__(self, html_content: List[str], css_content: str):
+        """Stores compiled HTML and CSS content.
+
+        :param html_content: The compiled HTML code of each page in the
+            website.
+        :type html_content: List[str]
+        :param css_content: The compiled CSS code of the website, shared across
+            all pages.
+        :type css_content: str
+        """
+        super().__init__()
+        self.html_content = html_content
+        self.css_content = css_content

webwidgets/website/website.py

@@ -0,0 +1,88 @@
+# =======================================================================
+#
+#  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 .compiled_website import CompiledWebsite
+from typing import Any, Callable, List
+from webwidgets.compilation.css import compile_css, CSSRule, apply_css
+from webwidgets.utility.representation import ReprMixin
+from webwidgets.widgets.containers.page import Page
+
+
+class Website(ReprMixin):
+    """A collection of :py:class:`Page` objects that make up the structure of a
+    web site."""
+
+    def __init__(self, pages: List[Page] = None):
+        """Creates a new website with an optional list of pages.
+
+        :param pages: The pages of the website. Defaults to an empty list.
+        :type pages: List[Page]
+        """
+        super().__init__()
+        self.pages = [] if pages is None else pages
+
+    def add(self, page: Page):
+        """Adds a new page to the website.
+
+        :param page: The page to be added.
+        :type page: Page
+        """
+        self.pages.append(page)
+
+    def compile(self,
+                collapse_empty: bool = True,
+                css_file_name: str = "styles.css",
+                force_one_line: bool = False,
+                indent_level: int = 0,
+                indent_size: int = 4,
+                rule_namer: Callable[[List[CSSRule], int], str] = None,
+                **kwargs: Any) -> CompiledWebsite:
+        """Compiles the website into HTML and CSS code.
+
+        :param collapse_empty: See :py:meth:`HTMLNode.to_html`.
+        :type collapse_empty: bool
+        :param css_file_name: See :py:meth:`Page.build`.
+        :type css_file_name: str
+        :param force_one_line: See :py:meth:`HTMLNode.to_html`.
+        :type force_one_line: bool
+        :param indent_level: See :py:meth:`HTMLNode.to_html`.
+        :type indent_level: int
+        :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 kwargs: See :py:meth:`HTMLNode.to_html`.
+        :type kwargs: Any
+        :return: A new :py:class:`CompiledWebsite` object containing the
+            compiled HTML and CSS code.
+        :rtype: CompiledWebsite
+        """
+        # Building the HTML representation of each page
+        trees = [page.build(css_file_name=css_file_name)
+                 for page in self.pages]
+
+        # Compiling HTML and CSS code
+        compiled_css = compile_css(trees, rule_namer)
+        for tree in trees:
+            apply_css(compiled_css, tree)
+        html_content = [tree.to_html(
+            collapse_empty=collapse_empty,
+            force_one_line=force_one_line,
+            indent_level=indent_level,
+            indent_size=indent_size,
+            **kwargs
+        ) for tree in trees]
+        css_content = compiled_css.to_css(indent_size=indent_size)
+
+        # Storing the result in a new CompiledWebsite object
+        return CompiledWebsite(html_content, css_content)

webwidgets/widgets/__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 .containers import *
+from .widget import Widget

webwidgets/widgets/containers/__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 .container import Container
+from .page import Page

webwidgets/widgets/containers/container.py

@@ -0,0 +1,38 @@
+# =======================================================================
+#
+#  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 List
+from webwidgets.widgets.widget import Widget
+
+
+class Container(Widget):
+    """
+    A widget that can contain other widgets.
+    """
+
+    def __init__(self, widgets: List[Widget] = None):
+        """Creates a new Container with optional widgets inside.
+
+        :param widgets: A list of widgets to be contained within the container.
+                    Defaults to an empty list.
+        :type widgets: List[Widget]
+        """
+        super().__init__()
+        self.widgets = [] if widgets is None else widgets
+
+    def add(self, widget: Widget) -> None:
+        """Adds a widget to the container.
+
+        :param widget: The widget to add to the container.
+        :type widget: Widget
+        """
+        self.widgets.append(widget)

webwidgets/widgets/containers/page.py

@@ -0,0 +1,59 @@
+# =======================================================================
+#
+#  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 webwidgets.compilation.html.html_node import RootNode
+from webwidgets.compilation.html.html_tags import Body, Doctype, Head, Html, \
+    Link
+
+
+class Page(Container):
+    """A widget representing a web page. It contains other widgets and is
+    responsible for laying them out within the page.
+    """
+
+    def build(self, css_file_name: str = "styles.css") -> RootNode:
+        """Builds the HTML representation of the page.
+
+        This method constructs an HTML structure that includes a doctype
+        declaration, a head section with meta tags, and a body section
+        containing the widgets. The widgets are rendered recurisvely by calling
+        their :py:meth:`build` method.
+
+        :param css_file_name: The name of the CSS file to link to the page if
+            the page elements contain any styles. Defaults to "styles.css".
+        :type css_file_name: str
+        :return: An :py:class:`RootNode` object representing the page.
+        :rtype: RootNode
+        """
+        # Building nodes from the page's widgets
+        nodes = [w.build() for w in self.widgets]
+
+        # Initializing the head section of the page
+        head = Head()
+
+        # Checking if there is any style sheet to link to the page.
+        # To do so, we just check if any child node has a non-empty style.
+        if any(style for n in nodes for style in n.get_styles().values()):
+            head.add(Link(
+                attributes={"href": css_file_name, "rel": "stylesheet"}
+            ))
+
+        # Building the HTML representation of the page
+        return RootNode(
+            children=[
+                Doctype(),
+                Html(
+                    children=[head, Body(children=nodes)]
+                )
+            ]
+        )

webwidgets/widgets/widget.py

@@ -0,0 +1,34 @@
+# =======================================================================
+#
+#  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 webwidgets.compilation.html.html_node import HTMLNode
+from webwidgets.utility.representation import ReprMixin
+
+
+class Widget(ABC, ReprMixin):
+    """
+    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.
+    """
+
+    @abstractmethod
+    def build(self) -> HTMLNode:
+        """Builds the widget and returns the corresponding :py:class:`HTMLNode`
+        object.
+
+        This method must be overridden by subclasses to create specific HTML
+        elements.
+        """
+        pass

webwidgets-1.0.0.dist-info/METADATA

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: webwidgets
+Version: 1.0.0
+Summary: A Python package for designing web UIs.
+Project-URL: Source code, https://github.com/mlaasri/WebWidgets
+Author: mlaasri
+License-File: LICENSE
+Keywords: design,webui
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# WebWidgets
+
+![CI Status](https://img.shields.io/github/actions/workflow/status/mlaasri/WebWidgets/ci-full.yml?branch=main)
+
+A Python package for creating web UIs
+
+## Installation
+
+You can install **WebWidgets** with `pip`. To install the latest stable version, run:
+
+```bash
+pip install webwidgets
+```
+
+## Usage
+
+**WebWidgets** allows you to create custom widgets and build websites with them. For example:
+
+```python
+import webwidgets as ww
+from webwidgets.compilation.html import HTMLNode, RawText
+
+# A <div> element
+class Div(HTMLNode):
+    pass
+
+# A simple text widget
+class Text(ww.Widget):
+    def build(self):
+        return Div([RawText("Hello, World!")])
+
+# A website with one page containing a Text widget
+page = ww.Page([Text()])
+website = ww.Website([page])
+
+# Compile the website into HTML code
+compiled = website.compile()
+print(compiled.html_content[0])
+```
+
+Prints the following result:
+
+```console
+<!DOCTYPE html>
+<html>
+    <head></head>
+    <body>
+        <div>
+            Hello, World!
+        </div>
+    </body>
+</html>
+```

webwidgets-1.0.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+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,,

webwidgets-0.2.0.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.4
-Name: webwidgets
-Version: 0.2.0
-Summary: A Python package for designing web UIs.
-Project-URL: Source code, https://github.com/mlaasri/WebWidgets
-Author: mlaasri
-License-File: LICENSE
-Keywords: design,webui
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python :: 3
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
-# WebWidgets
-
-![CI Status](https://img.shields.io/github/actions/workflow/status/mlaasri/WebWidgets/ci-full.yml?branch=main)
-
-A Python package for creating web UIs

webwidgets-0.2.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-webwidgets/__init__.py,sha256=jkCnUIqDE1LjArrZKtl1Bpm9bf-ZmLUP5JBRTh3gayA,481
-webwidgets/compilation/__init__.py,sha256=hb61nhmPTghIzuA_hun98xT5Ngv7QFAgMHD44g-9uOo,433
-webwidgets/compilation/css/__init__.py,sha256=Yzk_Bq1ey8Bf4dcKNd_priwj6_DA9CwG9wFs-BbZRGE,449
-webwidgets/compilation/css/css.py,sha256=8VjlXQtjY2fuhg49VtUi1RZF__Z7-qtj9-FAw3ZAtZA,7160
-webwidgets/compilation/html/__init__.py,sha256=NRccbCUKdhmK51MnYFO8q1sS8fWhAggRnMiGDG7lQMQ,505
-webwidgets/compilation/html/html_node.py,sha256=IEkb_zfIexU59cEk2Gf7nBo9Tm13DN_siLF7TBIGF1k,10095
-webwidgets/compilation/html/html_tags.py,sha256=U2HmhLkV6BOqTmgvIMlmMCQysQ7i2nEAVWJzZe74ucA,1388
-webwidgets/utility/__init__.py,sha256=_L0RxTAzAhjgZqg0eKEqpCJJeN_W2P9p5Clu7PETqCQ,448
-webwidgets/utility/sanitizing.py,sha256=OKJRDqk-OXYCWeK6ie3GdfQvb49wTs93kd971mg5oK0,5770
-webwidgets/utility/validation.py,sha256=bUjpiGP59GW3DPvQ1hwR5ezBMmcSd6v4xlDLwTHZv_A,4261
-webwidgets-0.2.0.dist-info/METADATA,sha256=WDQK0YqoVt7imhRbXDw3QjrG9UgCflSvbHYDiNRM1mU,550
-webwidgets-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-webwidgets-0.2.0.dist-info/licenses/LICENSE,sha256=LISw1mw5eK6i8adFSlx6zltZxrJFwurngVdZAEU8g_I,1064
-webwidgets-0.2.0.dist-info/RECORD,,