quirl 0.0.1__tar.gz

quirl-0.0.1/AUTHORS.md

@@ -0,0 +1,12 @@
+# Authors
+
+Brian Musakwa <digreatbrian@gmail.com>
+
+## Sole Developer and Owner
+Brian Musakwa is the sole developer and owner of this software.
+
+## Acknowledgements
+Special thanks to Guido van Rossum for creating Python, which made this project possible.
+
+## Project History
+Quirl was created on 25 August 2026.

quirl-0.0.1/LICENSE

@@ -0,0 +1,29 @@
+Copyright (c) 2026 Duck Framework
+Copyright (c) 2026 Brian Musakwa
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+    1. Redistributions of source code must retain the above copyright notice,
+       this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in the
+       documentation and/or other materials provided with the distribution.
+
+    3. Neither the name of Duck nor the names of its contributors may be used
+       to endorse or promote products derived from this software without
+       specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

quirl-0.0.1/MANIFEST.in

@@ -0,0 +1,7 @@
+include LICENSE
+include AUTHORS.md
+include README.md
+recursive-include quirl *
+exclude quirl/**/__pycache__
+exclude quirl/**/__pycache__/*.pyc
+

quirl-0.0.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: quirl
+Version: 0.0.1
+Summary: A reusable UI component library for Duck Framework's Lively reactive components.
+Author-email: Brian Musakwa <digreatbrian@gmail.com>
+Maintainer-email: Brian Musakwa <digreatbrian@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/duckframework/quirl
+Project-URL: Documentation, https://quirl.duckframework.com
+Project-URL: Source, https://github.com/duckframework/quirl
+Project-URL: Issues, https://github.com/duckframework/quirl/issues
+Project-URL: Contribution, https://duckframework.com/contribute?pkg=quirl
+Keywords: duck framework,duck,lively,lively components,reactive ui,server-side rendering,ui components,component library,web components,python ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: User Interfaces
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: duckframework>=2.3.1
+Dynamic: license-file
+
+# Quirl
+
+![Quirl Wordmark](./images/quirl-wordmark.svg)
+
+A reusable UI component library for [Duck Framework's](https://duckframework.com) Lively reactive system.
+
+Build consistent, themeable interfaces in pure Python — no separate frontend toolchain, no JavaScript bundling, no build steps for your UI logic.
+
+---
+
+## What is quirl?
+
+quirl provides a structured foundation for creating and documenting Duck Lively components. It handles theming, animation demos, and static documentation generation so you can focus on building interfaces, not boilerplate.
+
+- **Themeable by default** — Design tokens flow through CSS custom properties; every component inherits from a shared theme without hardcoded values.
+- **Self-documenting** — Components declare their own usage docs via markdown docstrings. A build script turns those into a static gallery.
+- **Animated demos without a server** — Wrap any component in a Demo container to generate pure HTML/CSS/JS showcases. Deploy to GitHub Pages with zero hosting cost.
+- **No inheritance lock-in** — The demo system works with any Duck component, built-in or third-party, without requiring base class changes.
+
+---
+
+## Installation
+
+```bash
+pip install quirl
+```
+
+Requires Python 3.10+ and `duckframework>=2.3.1`.
+
+---
+
+## Quick start
+
+### 1. Define a theme
+
+```python
+from quirl.theme import Theme
+
+dark = Theme(
+    name="dark",
+    accent_color="#F5C842",
+    surface_color="#111318",
+)
+
+# Update the global theme
+Theme.current = dark
+```
+
+### 2. Create a component
+
+Inherit from Duck's built-in components. Write your docs as a markdown class docstring:
+
+```python
+from duck.html.components.label import Label
+
+class StatusLabel(Label):
+    """
+    A themed label for displaying status text.
+
+    Usage:
+    ```python
+    StatusLabel(text="Active", color="green")
+    ```
+
+    Required Props:
+    - text: Display text
+    
+    Optional Props:
+    - color: The text color for the label
+    """
+    
+    # Preview kwargs for the demo
+    docs_preview_kwargs = {"text": "Preview", "color": "#3b82f6"}
+    
+    # Demo animation steps
+    docs_animation_steps = [
+        {"delay": 1000, "cursor": {"top": "50%", "left": "50%"}},
+        {"delay": 500, "target": "span", "click": True},
+    ]
+
+    def on_create(self):
+        super().on_create()
+        
+        # Update style
+        self.style.update({
+            "border-radius": "9999px",
+            "padding": "4px 12px",
+            "font-weight": "500",
+        })
+```
+
+### 3. Render a static demo
+
+```python
+from duck.html.components.container import Container
+from duck.html.components.button import Button
+from duck.html.components.input import Input
+
+from quirl.components import Demo
+
+
+# Demo a built-in Button
+button_demo = Demo(
+    component=Button(text="Submit", bg_color="blue", color="white"),
+    steps=[
+        {"delay": 1000, "cursor": {"target": "button"}},
+        {"delay": 500, "target": "button", "click": True},
+        {"delay": 2000},
+    ],
+    title="Button",
+)
+
+# Demo a built-in Input
+input_demo = Demo(
+    component=Input(type="text", name="email", placeholder="Email"),
+    steps=[
+        {"delay": 800, "cursor": {"top": "50%", "left": "30%"}},
+        {"delay": 1000, "target": "input", "click": True},
+        {"delay": 1500},
+    ],
+    title="Input",
+)
+
+# Group components
+container = Container(children=[button_demo, input_demo])
+
+# Render to static HTML
+html = container.render()
+```
+
+Deploy the output to GitHub Pages, Netlify, or any static host. No Python runtime required on the server.
+
+---
+
+## Architecture
+
+quirl is organized around three concerns: theming, documentation, and animation demos.
+
+The theme system lives at the package root and provides extensible design tokens through a global class-level registry. Access the active theme anywhere via `Theme.current`.
+
+The animation demo system lives under `quirl.components.animation.demo` and wraps any Duck component for static HTML output. It generates self-contained CSS animations and click simulations without a WebSocket connection or Python runtime on the client.
+
+---
+
+## Development
+
+**quirl** follows the Duck Framework code style:
+
+- Google-style docstrings on every module, class, and method.
+- Constructor-based initialization via kwargs only.
+- No private-style method names (build_nav, not _build_nav).
+- Components live in quirl/components/, themes and utilities at the package root.
+
+---
+
+## License
+
+See [LICENSE](./LICENSE).
+

quirl-0.0.1/README.md

@@ -0,0 +1,159 @@
+# Quirl
+
+![Quirl Wordmark](./images/quirl-wordmark.svg)
+
+A reusable UI component library for [Duck Framework's](https://duckframework.com) Lively reactive system.
+
+Build consistent, themeable interfaces in pure Python — no separate frontend toolchain, no JavaScript bundling, no build steps for your UI logic.
+
+---
+
+## What is quirl?
+
+quirl provides a structured foundation for creating and documenting Duck Lively components. It handles theming, animation demos, and static documentation generation so you can focus on building interfaces, not boilerplate.
+
+- **Themeable by default** — Design tokens flow through CSS custom properties; every component inherits from a shared theme without hardcoded values.
+- **Self-documenting** — Components declare their own usage docs via markdown docstrings. A build script turns those into a static gallery.
+- **Animated demos without a server** — Wrap any component in a Demo container to generate pure HTML/CSS/JS showcases. Deploy to GitHub Pages with zero hosting cost.
+- **No inheritance lock-in** — The demo system works with any Duck component, built-in or third-party, without requiring base class changes.
+
+---
+
+## Installation
+
+```bash
+pip install quirl
+```
+
+Requires Python 3.10+ and `duckframework>=2.3.1`.
+
+---
+
+## Quick start
+
+### 1. Define a theme
+
+```python
+from quirl.theme import Theme
+
+dark = Theme(
+    name="dark",
+    accent_color="#F5C842",
+    surface_color="#111318",
+)
+
+# Update the global theme
+Theme.current = dark
+```
+
+### 2. Create a component
+
+Inherit from Duck's built-in components. Write your docs as a markdown class docstring:
+
+```python
+from duck.html.components.label import Label
+
+class StatusLabel(Label):
+    """
+    A themed label for displaying status text.
+
+    Usage:
+    ```python
+    StatusLabel(text="Active", color="green")
+    ```
+
+    Required Props:
+    - text: Display text
+    
+    Optional Props:
+    - color: The text color for the label
+    """
+    
+    # Preview kwargs for the demo
+    docs_preview_kwargs = {"text": "Preview", "color": "#3b82f6"}
+    
+    # Demo animation steps
+    docs_animation_steps = [
+        {"delay": 1000, "cursor": {"top": "50%", "left": "50%"}},
+        {"delay": 500, "target": "span", "click": True},
+    ]
+
+    def on_create(self):
+        super().on_create()
+        
+        # Update style
+        self.style.update({
+            "border-radius": "9999px",
+            "padding": "4px 12px",
+            "font-weight": "500",
+        })
+```
+
+### 3. Render a static demo
+
+```python
+from duck.html.components.container import Container
+from duck.html.components.button import Button
+from duck.html.components.input import Input
+
+from quirl.components import Demo
+
+
+# Demo a built-in Button
+button_demo = Demo(
+    component=Button(text="Submit", bg_color="blue", color="white"),
+    steps=[
+        {"delay": 1000, "cursor": {"target": "button"}},
+        {"delay": 500, "target": "button", "click": True},
+        {"delay": 2000},
+    ],
+    title="Button",
+)
+
+# Demo a built-in Input
+input_demo = Demo(
+    component=Input(type="text", name="email", placeholder="Email"),
+    steps=[
+        {"delay": 800, "cursor": {"top": "50%", "left": "30%"}},
+        {"delay": 1000, "target": "input", "click": True},
+        {"delay": 1500},
+    ],
+    title="Input",
+)
+
+# Group components
+container = Container(children=[button_demo, input_demo])
+
+# Render to static HTML
+html = container.render()
+```
+
+Deploy the output to GitHub Pages, Netlify, or any static host. No Python runtime required on the server.
+
+---
+
+## Architecture
+
+quirl is organized around three concerns: theming, documentation, and animation demos.
+
+The theme system lives at the package root and provides extensible design tokens through a global class-level registry. Access the active theme anywhere via `Theme.current`.
+
+The animation demo system lives under `quirl.components.animation.demo` and wraps any Duck component for static HTML output. It generates self-contained CSS animations and click simulations without a WebSocket connection or Python runtime on the client.
+
+---
+
+## Development
+
+**quirl** follows the Duck Framework code style:
+
+- Google-style docstrings on every module, class, and method.
+- Constructor-based initialization via kwargs only.
+- No private-style method names (build_nav, not _build_nav).
+- Components live in quirl/components/, themes and utilities at the package root.
+
+---
+
+## License
+
+See [LICENSE](./LICENSE).
+

quirl-0.0.1/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quirl"
+dynamic = ["version", "dependencies"]
+description = "A reusable UI component library for Duck Framework's Lively reactive components."
+readme = "README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE", "AUTHORS.md"]
+authors = [
+    { name = "Brian Musakwa", email = "digreatbrian@gmail.com" },
+]
+maintainers = [
+    { name = "Brian Musakwa", email = "digreatbrian@gmail.com" },
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Web Environment",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: User Interfaces",
+]
+keywords = [
+    "duck framework",
+    "duck",
+    "lively",
+    "lively components",
+    "reactive ui",
+    "server-side rendering",
+    "ui components",
+    "component library",
+    "web components",
+    "python ui",
+]
+
+[project.urls]
+Homepage = "https://github.com/duckframework/quirl"
+Documentation = "https://quirl.duckframework.com"
+Source = "https://github.com/duckframework/quirl"
+Issues = "https://github.com/duckframework/quirl/issues"
+Contribution = "https://duckframework.com/contribute?pkg=quirl"
+
+[project.scripts]
+duck = "quirl.__main__:cli"
+
+[tool.setuptools.dynamic]
+version = {attr = "quirl.__version__"}
+dependencies = { file = ["requirements.txt"] }
+
+[tool.setuptools.packages.find]
+include = ["quirl*"]
+where = ["."]

quirl-0.0.1/quirl/__init__.py

@@ -0,0 +1,18 @@
+"""
+Quirl — a modern, iOS-inspired premium component pack for Duck Framework.
+
+Add the shared keyframes stylesheet once per page so animated components
+work:
+
+```python
+from quirl.styles import quirl_global_styles
+
+page.add_to_head(quirl_global_styles())
+```
+"""
+from quirl.version import version
+
+
+__author__ = "Brian Musakwa"
+__email__ = "digreatbrian@gmail.com"
+__version__ = version

quirl-0.0.1/quirl/__main__.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+"""
+Main entry to Quirl command-line tool.
+"""
+import os
+import sys
+import click
+import setproctitle
+
+from quirl.version import version
+
+
+@click.group(invoke_without_command=True)
+@click.option('-V', '--version', is_flag=True, help="Show the version and exit.")
+@click.pass_context
+def cli(ctx, version):
+    """
+    Quirl CLI.
+    """
+    subcommand = ctx.invoked_subcommand
+    
+    if subcommand:
+        # Set process name dynamically
+        setproctitle.setproctitle(f"quirl-{subcommand}")
+    
+    if version:
+        # Show the version
+        click.echo(version)
+    
+    elif not ctx.invoked_subcommand:
+        # Print usage if no subcommands are invoked
+        click.echo(ctx.get_help())
+
+
+if __name__ == "__main__":
+    cli()

quirl-0.0.1/quirl/components/__init__.py

@@ -0,0 +1,63 @@
+"""
+Modern UI components for Duck Framework's Lively system.
+
+Components are lazily imported on first access (PEP 562), so
+`import quirl.components` stays cheap no matter how many components
+the pack grows to — only the submodule you actually touch gets loaded.
+
+Adding a new component only requires one line in _COMPONENT_MAP below;
+no top-level import statement needed.
+"""
+
+import importlib
+
+
+# Maps public name -> "submodule:attribute" to import lazily
+_COMPONENT_MAP = {
+    "Badge": "badge:Badge",
+    "Avatar": "avatar:Avatar",
+    "Alert": "alert:Alert",
+    "Skeleton": "skeleton:Skeleton",
+    "Tag": "tag:Tag",
+    "Spinner": "spinner:Spinner",
+    "Divider": "divider:Divider",
+    "CodeBlock": "code_block:CodeBlock",
+    "Demo": "animation.demo:Demo",
+    "Documentor": "documentor:Documentor",
+}
+
+__all__ = list(_COMPONENT_MAP)
+
+
+def __getattr__(name: str):
+    """
+    Lazily import and cache a component on first access.
+
+    Args:
+        name: The attribute being accessed, e.g. "Badge".
+
+    Returns:
+        The requested component class.
+
+    Raises:
+        AttributeError: If name isn't a known component.
+    """
+    target = _COMPONENT_MAP.get(name)
+
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_path, attr_name = target.split(":")
+    module = importlib.import_module(f".{module_path}", __name__)
+    value = getattr(module, attr_name)
+
+    # Cache directly on the module so repeated access skips __getattr__
+    globals()[name] = value
+    return value
+
+
+def __dir__():
+    """
+    Report the public component names for tab-completion and dir().
+    """
+    return sorted(__all__)