casca 0.1.0__tar.gz

casca-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Casca Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

casca-0.1.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: casca
+Version: 0.1.0
+Summary: Native Python CLI UI library with CSS-like styling
+Author-email: Abdallah <abdalla.zain2004@gmail.com>
+License: MIT
+Keywords: tui,cli,terminal,ui,css,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: chatbot
+Requires-Dist: groq>=0.20.0; extra == "chatbot"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.8.0; extra == "docs"
+Dynamic: license-file
+
+# Casca
+
+Casca is a lightweight, native Python TUI library with a DOM-like widget tree and CSS-style theming.
+
+## Features
+
+- Zero core dependencies (standard library runtime)
+- Declarative widgets (`Container`, `Label`, `Input`, `Button`, `Card`, `Header`, `ScrollView`)
+- CSS-like style parsing and cascade
+- Keyboard and mouse event handling in raw terminal mode
+- Real examples including login screen, dashboard, and Groq chatbot
+
+## Quick Start
+
+```python
+from casca import Container, Label, run_app
+
+CSS = """
+#root {
+    padding: 1;
+    border: ascii;
+}
+"""
+
+
+
+ui_tree = Container(
+    Label("Hello from Casca"),
+    id="root",
+)
+
+if __name__ == "__main__":
+    run_app(ui_tree, css=CSS)
+```
+
+## Run Use Cases
+
+```bash
+python3 -m use_cases.login_screen
+python3 -m use_cases.dashboard
+python3 -m use_cases.chatbot
+```
+
+`use_cases.chatbot` requires `groq` and a `GROQ_API_KEY`.
+
+
+## Project Layout
+
+- `casca/`: core library
+- `use_cases/`: real apps built with Casca
+- `examples/`: smaller demos
+- `docs/`: MkDocs content
+
+## License
+
+MIT

casca-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Casca
+
+Casca is a lightweight, native Python TUI library with a DOM-like widget tree and CSS-style theming.
+
+## Features
+
+- Zero core dependencies (standard library runtime)
+- Declarative widgets (`Container`, `Label`, `Input`, `Button`, `Card`, `Header`, `ScrollView`)
+- CSS-like style parsing and cascade
+- Keyboard and mouse event handling in raw terminal mode
+- Real examples including login screen, dashboard, and Groq chatbot
+
+## Quick Start
+
+```python
+from casca import Container, Label, run_app
+
+CSS = """
+#root {
+    padding: 1;
+    border: ascii;
+}
+"""
+
+
+
+ui_tree = Container(
+    Label("Hello from Casca"),
+    id="root",
+)
+
+if __name__ == "__main__":
+    run_app(ui_tree, css=CSS)
+```
+
+## Run Use Cases
+
+```bash
+python3 -m use_cases.login_screen
+python3 -m use_cases.dashboard
+python3 -m use_cases.chatbot
+```
+
+`use_cases.chatbot` requires `groq` and a `GROQ_API_KEY`.
+
+
+## Project Layout
+
+- `casca/`: core library
+- `use_cases/`: real apps built with Casca
+- `examples/`: smaller demos
+- `docs/`: MkDocs content
+
+## License
+
+MIT

casca-0.1.0/casca/__init__.py

@@ -0,0 +1,37 @@
+from .core.app import App
+from .core.events import KeyEvent, ResizeEvent
+from .core.terminal import RawTerminal, get_terminal_size
+from .core.ansi import color, Color, BackColor, move_cursor, CLEAR_SCREEN, RESET
+from .dom.node import Widget
+from .components.base import Container, Label, Button
+from .components.forms import Checkbox, Input
+from .components.panels import Card, Header
+from .components.scroll import ScrollView
+from .style.css import parse_css
+
+__all__ = [
+    "App",
+    "KeyEvent",
+    "ResizeEvent",
+    "RawTerminal",
+    "get_terminal_size",
+    "color",
+    "Color",
+    "BackColor",
+    "move_cursor",
+    "CLEAR_SCREEN",
+    "RESET",
+    "Widget",
+    "Container",
+    "Label",
+    "Button",
+    "Checkbox",
+    "Input",
+    "Card",
+    "Header",
+    "ScrollView",
+    "parse_css",
+]
+
+from .core.app import run_app
+__all__.append('run_app')

casca-0.1.0/casca/components/__init__.py

@@ -0,0 +1 @@
+from .scroll import ScrollView

casca-0.1.0/casca/components/base.py

@@ -0,0 +1,78 @@
+from ..dom.node import Widget
+from ..core.ansi import move_cursor
+from ..core.events import MouseEvent
+import textwrap
+
+class Container(Widget):
+    """A generic div-like container for laying out children."""
+    tag = 'container'
+
+
+class Label(Widget):
+    """Displays text. Implements text-wrapping based on layout boundaries."""
+    tag = 'label'
+
+    def __init__(self, text: str, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.text = text
+        self.lines = []
+
+    def calculate_layout(self, available_width: int, available_height: int) -> tuple[int, int]:
+        padding = int(self.style.get('padding', 0))
+        margin = int(self.style.get('margin', 0))
+        
+        # Calculate available inner width to check wrapping
+        inner_width = available_width - (margin * 2) - (padding * 2)
+        w_prop = self.props.get('width') or self.style.get('width')
+        if w_prop:
+            inner_width = int(w_prop) - (padding * 2)
+            
+        # Parse Text 
+        self.lines = []
+        for line in self.text.split('\\n'):
+            if inner_width > 0:
+                wrapped = textwrap.wrap(line, max(1, inner_width))
+                if not wrapped:
+                    self.lines.append("")
+                else:
+                    self.lines.extend(wrapped)
+            else:
+                self.lines.append(line)
+        
+        self.content_height = len(self.lines)
+        self.content_width = max([len(l) for l in self.lines] + [0])
+        
+        self.width = self.content_width + padding * 2
+        self.height = self.content_height + padding * 2
+        
+        return self.width + margin * 2, self.height + margin * 2
+
+    def render_content(self, app):
+        padding = int(self.style.get('padding', 0))
+        
+        for i, line in enumerate(self.lines):
+            app.draw_text(self.x + padding + 1, self.y + padding + i + 1, line)
+
+
+class Button(Label):
+    """Clickable element. Triggers on_click function."""
+    tag = 'button'
+
+    def __init__(self, text: str, *args, on_click=None, **kwargs):
+        super().__init__(text, *args, **kwargs)
+        self.on_click = on_click
+        
+    def handle_input(self, event) -> bool:
+        if event.key == '\r' or event.key == ' ':  # Enter or Space
+            if self.on_click:
+                self.on_click(event)
+                return True
+        return super().handle_input(event)
+
+    def on_mouse(self, event: MouseEvent) -> bool:
+        # Trigger on mouse release for primary button
+        if event.button == 0 and not event.pressed:
+            if self.on_click:
+                self.on_click(event)
+            return True
+        return False

casca-0.1.0/casca/components/forms.py

@@ -0,0 +1,101 @@
+from ..dom.node import Widget
+from ..core.events import KeyEvent, MouseEvent
+from ..core.ansi import move_cursor
+from .base import Label, Container
+
+class Checkbox(Widget):
+    """A selectable checkbox."""
+    tag = 'checkbox'
+
+    def __init__(self, label_text: str, checked: bool = False, *args, on_change=None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.label_text = label_text
+        self.checked = checked
+        self.on_change = on_change
+
+    def calculate_layout(self, available_width: int, available_height: int) -> tuple[int, int]:
+        self.content_height = 1
+        self.content_width = len(self.label_text) + 4 # "[x] " + text
+        
+        padding = int(self.style.get('padding', 0))
+        margin = int(self.style.get('margin', 0))
+        
+        self.width = self.content_width + padding * 2
+        self.height = self.content_height + padding * 2
+        return self.width + margin * 2, self.height + margin * 2
+
+    def render_content(self, app):
+        padding = int(self.style.get('padding', 0))
+        state_char = 'x' if self.checked else ' '
+        
+        app.draw_text(self.x + padding + 1, self.y + padding + 1, f"[{state_char}] {self.label_text}")
+
+    def handle_input(self, event: KeyEvent) -> bool:
+        if event.key == '\r' or event.key == ' ':  # Toggle on Enter or Space
+            self.checked = not self.checked
+            if self.on_change:
+                self.on_change(self.checked)
+            return True
+        return super().handle_input(event)
+
+    def on_mouse(self, event: MouseEvent) -> bool:
+        # Toggle on left click release
+        if event.button == 0 and not event.pressed:
+            self.checked = not self.checked
+            if self.on_change:
+                self.on_change(self.checked)
+            return True
+        return False
+
+class Input(Widget):
+    """A simple one-line text input field."""
+    tag = 'input'
+
+    def __init__(self, placeholder: str = "", default_value: str = "", *args, on_submit=None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.placeholder = placeholder
+        self.value = default_value
+        self.on_submit = on_submit
+
+        # Make input take up full remaining width by default unless specified
+        if 'width' not in self.props:
+            self.style['width'] = "20" 
+
+    def calculate_layout(self, available_width: int, available_height: int) -> tuple[int, int]:
+        self.content_height = 1
+        padding = int(self.style.get('padding', 0))
+        margin = int(self.style.get('margin', 0))
+        
+        self.width = self.props.get('width', int(self.style.get('width', available_width)))
+        self.height = self.content_height + padding * 2
+        
+        return self.width + margin * 2, self.height + margin * 2
+
+    def render_content(self, app):
+        padding = int(self.style.get('padding', 0))
+        
+        display_text = self.value if self.value else self.placeholder
+        
+        if self.focused:
+            display_text += "█"
+            
+        app.draw_text(self.x + padding + 1, self.y + padding + 1, display_text[:self.width - (padding * 2)])
+
+    def on_mouse(self, event: MouseEvent) -> bool:
+        if event.pressed:
+            return True
+        return False
+
+    def handle_input(self, event: KeyEvent) -> bool:
+        # Simplistic typing
+        if event.key in ('\x08', '\x7f', '\b'): # Backspace / Delete
+            self.value = self.value[:-1]
+            return True
+        elif event.key in ('\r', '\n'):
+            if self.on_submit:
+                self.on_submit(self.value)
+            return True
+        elif event.is_printable:
+            self.value += event.key
+            return True
+        return super().handle_input(event)

casca-0.1.0/casca/components/panels.py

@@ -0,0 +1,26 @@
+from .base import Container, Label
+
+class Card(Container):
+    """A Container with predefined standard styling parameters for typical Card UI."""
+    tag = 'card'
+
+    def __init__(self, title: str, *children, **kwargs):
+        # Insert a Label as the first child to serve as the card title
+        title_label = Label(f" {title} ", classes="card-title")
+        super().__init__(title_label, *children, **kwargs)
+        
+    def resolve_styles(self, stylesheet: dict):
+        # We can dynamically force a border on cards if not overriden
+        if 'border' not in self.style:
+            self.style['border'] = 'ascii'
+        super().resolve_styles(stylesheet)
+
+
+class Header(Container):
+    """A wide container designed to sit at the top of an app."""
+    tag = 'header'
+
+    def resolve_styles(self, stylesheet: dict):
+        # A header should naturally want to span 100% of width 
+        # (Though our layout engine is basic right now, we can set width to a high number or handled by parent layout later)
+        super().resolve_styles(stylesheet)

casca-0.1.0/casca/components/scroll.py

@@ -0,0 +1,148 @@
+from ..dom.node import Widget
+from ..core.events import KeyEvent, MouseEvent
+from ..core.ansi import RESET
+
+class ScrollView(Widget):
+    """A container that clips its children vertically and allows scrolling."""
+    tag = 'scrollview'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.scroll_y = 0
+        self.max_scroll = 0
+
+    def calculate_layout(self, available_width: int, available_height: int) -> tuple[int, int]:
+        padding = int(self.style.get('padding', 0))
+        margin = int(self.style.get('margin', 0))
+        border_width = 1 if 'border' in self.style else 0
+
+        self.width = self.props.get('width', int(self.style.get('width', available_width)))
+        
+        set_height = self.props.get('height') or self.style.get('height')
+        if set_height:
+            self.height = int(set_height)
+        else:
+            self.height = available_height
+            
+        inner_width = max(0, self.width - 2*(padding + border_width))
+        
+        current_y = 0
+        max_child_width = 0
+        
+        # Calculate children sizes assuming infinite height
+        for child in self.children:
+            child.x = self.x + padding + border_width
+            child.y = self.y + padding + border_width + current_y
+            
+            child_w, child_h = child.calculate_layout(inner_width, 9999)
+            current_y += child_h
+            max_child_width = max(max_child_width, child_w)
+            
+        self.content_height = current_y
+        self.content_width = max_child_width
+        
+        inner_height = max(0, self.height - 2*(padding + border_width))
+        self.max_scroll = max(0, self.content_height - inner_height)
+        
+        
+        # Determine if content grew to auto-scroll if requested
+        was_at_bottom = hasattr(self, '_last_max') and self.scroll_y >= self._last_max
+        is_first_layout = not hasattr(self, '_last_max')
+        
+        if self.props.get('scroll_to_bottom'):
+            if is_first_layout or was_at_bottom:
+                self.scroll_y = self.max_scroll
+                
+        self._last_max = self.max_scroll
+            
+        if self.scroll_y > self.max_scroll:
+            self.scroll_y = self.max_scroll
+        if self.scroll_y < 0:
+            self.scroll_y = 0
+            
+        # Apply scroll offset conceptually (modifying y directly for rendering)
+        # Note: If layout recalculates periodically, this is fine because we recalculate before render
+        self._apply_scroll_offset()
+        
+        return self.width + margin * 2, self.height + margin * 2
+
+    def _apply_scroll_offset(self):
+        def shift(node, offset):
+            node.y -= offset
+            for c in node.children:
+                shift(c, offset)
+                
+        for child in self.children:
+            shift(child, self.scroll_y)
+
+    def render(self, app):
+        padding = int(self.style.get('padding', 0))
+        border_width = 1 if 'border' in self.style else 0
+        
+        min_y = self.y + padding + border_width + 1
+        max_y = min_y + max(0, self.height - 2*(padding + border_width))
+        min_x = self.x + padding + border_width + 1
+        max_x = min_x + max(0, self.width - 2*(padding + border_width))
+        
+        prev_clip = getattr(app, 'clip_rect', None)
+        # We need to intersect with existing clip rect if any (skip for simplicity for now, assume 1 scrollview depth)
+        app.clip_rect = (min_y, max_y, min_x, max_x)
+        
+        self.apply_style(app)
+        
+        if 'background' in self.style:
+            for r in range(self.height):
+                app.draw_text(self.x + 1, self.y + r + 1, " " * self.width, apply_clip=False)
+            self.apply_style(app)
+
+        if self.style.get('border', 'none') != 'none':
+            self._draw_border(app)
+            
+        self._draw_scrollbar(app)
+
+        for child in self.children:
+            child.render(app)
+            self.apply_style(app)
+            
+        app.clip_rect = prev_clip
+        app.write(RESET)
+
+    def _draw_scrollbar(self, app):
+        inner_height = max(0, self.height - 2)
+        if self.max_scroll > 0 and inner_height > 0:
+            thumb_size = max(1, int(inner_height * (inner_height / (self.content_height or 1))))
+            thumb_pos = int((self.scroll_y / self.max_scroll) * (inner_height - thumb_size))
+            
+            for i in range(inner_height):
+                char = '█' if thumb_pos <= i < thumb_pos + thumb_size else '▒'
+                app.draw_text(self.x + self.width - 1, self.y + 2 + i, char, apply_clip=False)
+
+    def handle_input(self, event: KeyEvent) -> bool:
+        # Check kids first
+        if super().handle_input(event):
+            return True
+            
+        # Scroll up and down on arrow keys if we have standard keys mapping
+        if event.key == '\x1b[A': # Up Arrow
+            self.scroll_y = max(0, self.scroll_y - 1)
+            return True
+        elif event.key == '\x1b[B': # Down arrow
+            self.scroll_y = min(self.max_scroll, self.scroll_y + 1)
+            return True
+            
+        return False
+
+    def handle_wheel(self, event: MouseEvent, app) -> bool:
+        term_x = event.x - 1
+        term_y = event.y - 1
+
+        if self.x <= term_x < self.x + self.width and self.y <= term_y < self.y + self.height:
+            if event.button == 64:
+                self.scroll_y = max(0, self.scroll_y - 1)
+                if app._running: app._render_cycle()
+                return True
+            elif event.button == 65:
+                self.scroll_y = min(self.max_scroll, self.scroll_y + 1)
+                if app._running: app._render_cycle()
+                return True
+        return False

casca-0.1.0/casca/core/ansi.py

@@ -0,0 +1,48 @@
+from enum import Enum
+
+class Color(Enum):
+    BLACK = 30
+    RED = 31
+    GREEN = 32
+    YELLOW = 33
+    BLUE = 34
+    MAGENTA = 35
+    CYAN = 36
+    WHITE = 37
+    DEFAULT = 39
+
+class BackColor(Enum):
+    BLACK = 40
+    RED = 41
+    GREEN = 42
+    YELLOW = 43
+    BLUE = 44
+    MAGENTA = 45
+    CYAN = 46
+    WHITE = 47
+    DEFAULT = 49
+
+ESC = '\x1b['
+CLEAR_SCREEN = f"{ESC}2J"
+ALT_SCREEN_ON = f"{ESC}?1049h"
+ALT_SCREEN_OFF = f"{ESC}?1049l"
+HIDE_CURSOR = f"{ESC}?25l"
+SHOW_CURSOR = f"{ESC}?25h"
+MOUSE_ON = f"{ESC}?1000h{ESC}?1006h"
+MOUSE_OFF = f"{ESC}?1006l{ESC}?1000l"
+
+# Text Styling
+BOLD = f"{ESC}1m"
+FAINT = f"{ESC}2m"
+ITALIC = f"{ESC}3m"
+UNDERLINE = f"{ESC}4m"
+
+def move_cursor(x: int, y: int) -> str:
+    """Move cursor to 1-based x, y position."""
+    return f"{ESC}{y};{x}H"
+
+def color(fg: Color = Color.DEFAULT, bg: BackColor = BackColor.DEFAULT) -> str:
+    """Set foreground and background color."""
+    return f"{ESC}{fg.value};{bg.value}m"
+
+RESET = f"{ESC}0m"

casca-0.1.0/casca/core/app.py

@@ -0,0 +1,236 @@
+import sys
+import select
+import signal
+import re
+import os
+
+from .terminal import RawTerminal, get_terminal_size
+from .ansi import CLEAR_SCREEN, move_cursor, RESET
+from .events import KeyEvent, ResizeEvent, MouseEvent
+from ..style.css import parse_css
+
+class App:
+    """
+    The main application context and event loop.
+    Provides a base class for rendering and handling events.
+    """
+    css = ""
+
+    def __init__(self):
+        self._running = False
+        self._last_size = get_terminal_size()
+        
+        # Buffer to accumulate output before flushing (double buffer concept)
+        self._output_buffer = []
+        self._input_buffer = ""
+        
+        # DOM Root & Focus State
+        self.root = None
+        self.stylesheet = parse_css(self.css)
+        self.focused_widget = None
+        self.focused_id = None
+
+    def run(self):
+        """Starts the event loop."""
+        self._running = True
+
+        # Attach to SIGWINCH for resize events in Unix
+        try:
+            signal.signal(signal.SIGWINCH, self._handle_sigwinch)
+        except AttributeError:
+            # SIGWINCH is not available on all systems (e.g. Windows)
+            pass
+
+        with RawTerminal():
+            self._render_cycle()
+            
+            while self._running:
+                # Wait for input (0.05s timeout for 20 FPS refresh rate max)
+                dr, _, _ = select.select([sys.stdin], [], [], 0.05)
+                
+                if dr:
+                    # Read all available bytes
+                    try:
+                        data = os.read(sys.stdin.fileno(), 1024).decode('utf-8', errors='replace')
+                    except BlockingIOError:
+                        continue
+                    
+                    if not data:
+                        continue
+
+                    # Extract all SGR Mouse Events iteratively
+                    mouse_pattern = r'\x1b\[<(\d+);(\d+);(\d+)([mM])'
+                    for match in re.finditer(mouse_pattern, data):
+                        btn, x, y, state = match.groups()
+                        is_pressed = (state == 'M')
+                        mouse_evt = MouseEvent(x=int(x), y=int(y), button=int(btn), pressed=is_pressed)
+                        self.handle_mouse(mouse_evt)
+                        
+                    # Remove parsed mouse events
+                    data = re.sub(mouse_pattern, '', data)
+
+                    # Quick checks for remaining inputs
+                    if '\x03' in data or '\x04' in data:
+                        self.exit()
+                    
+                    # Split remaining ANSI escape codes or parse them.
+                    # For simplicity, if we see an escape sequence, treat the block roughly.
+                    # Otherwise handle pure characters
+                    i = 0
+                    while i < len(data):
+                        if data[i] == '\x1b':
+                            # Probably an escape sequence (like arrows)
+                            # Just capture roughly until a letter
+                            end = i + 1
+                            while end < len(data) and not data[end].isalpha() and data[end] != '~':
+                                end += 1
+                            if end < len(data): end += 1
+                            
+                            sub = data[i:end]
+                            self.handle_input(KeyEvent(key=sub, is_printable=False))
+                            i = end
+                        else:
+                            char = data[i]
+                            # Only handle printable or basic backspaces
+                            if char in ('\x08', '\x7f', '\r', '\n', '\t') or char.isprintable():
+                                # In raw mode, we might receive \r for enter.
+                                is_print = char.isprintable()
+                                if char in ('\r', '\n', '\t'):
+                                    is_print = False
+                                self.handle_input(KeyEvent(key=char, is_printable=is_print))
+                            i += 1
+                        
+                    # Request a re-render after an input if app is still running
+                    if self._running:
+                        self._render_cycle()
+                        
+                # Optionally check if size changed periodically if SIGWINCH failed
+                current_size = get_terminal_size()
+                if current_size != self._last_size:
+                    self._last_size = current_size
+                    self.handle_resize(ResizeEvent(*current_size))
+                    self._render_cycle()
+
+    def exit(self):
+        """Signals the app to break out of the event loop."""
+        self._running = False
+
+    def write(self, text: str):
+        """Appends output to the render buffer."""
+        self._output_buffer.append(text)
+
+    def draw_text(self, x: int, y: int, text: str, apply_clip=True):
+        """Helper to draw text with optional vertical clipping."""
+        if apply_clip and hasattr(self, 'clip_rect') and self.clip_rect:
+            min_y, max_y, min_x, max_x = self.clip_rect
+            if y < min_y or y >= max_y:
+                return
+            # horizontal clipping
+            if x < min_x:
+                text = text[min_x - x:]
+                x = min_x
+            if x + len(text) > max_x:
+                text = text[:max_x - x]
+            if not text:
+                return
+        self.write(move_cursor(x, y))
+        self.write(text)
+
+    def flush(self):
+        """Writes the entire render buffer to the stdout in one go to prevent flicker."""
+        if self._output_buffer:
+            sys.stdout.write("".join(self._output_buffer))
+            sys.stdout.flush()
+            self._output_buffer.clear()
+
+    def _render_cycle(self):
+        """Internal render pass to orchestrate drawing."""
+        self.write(CLEAR_SCREEN)
+        self.write(move_cursor(1, 1))
+        
+        # Call user's render method
+        self.render()
+        
+        self.write(RESET)
+        self.flush()
+
+    def _handle_sigwinch(self, signum, frame):
+        """Unix signal handler for terminal resize."""
+        size = get_terminal_size()
+        self._last_size = size
+        self.handle_resize(ResizeEvent(width=size[0], height=size[1]))
+        if self._running:
+            self._render_cycle()
+
+    # --- Methods to be overridden by subclasses (User API) ---
+
+    def handle_input(self, event: KeyEvent):
+        """Triggered when a key is pressed."""
+        # By default, press 'q' to quit. Subclasses can override.
+        if event.key == 'q':
+            self.exit()
+            
+        # Prioritize focused widget, else try routing through the DOM
+        consumed = False
+        if self.focused_widget:
+            consumed = self.focused_widget.handle_input(event)
+            
+        if not consumed and self.root:
+            self.root.handle_input(event)
+
+    def handle_mouse(self, event: MouseEvent):
+        """Triggered on mouse interaction."""
+        if self.root:
+            self.root.handle_mouse(event, self)
+
+    def handle_resize(self, event: ResizeEvent):
+        """Triggered when the terminal window changes size."""
+        pass
+
+    def build_ui(self):
+        """Override this to return the root widget tree."""
+        return None
+
+    def render(self):
+        """
+        The main rendering function.
+        Rebuilds styling and layout, then renders the full Widget tree.
+        """
+        if not self.root:
+            self.root = self.build_ui()
+            
+            # Restore focus after a UI rebuild if an element ID was previously focused
+            if self.focused_id:
+                def restore_focus(node):
+                    if node.id == self.focused_id:
+                        node.focused = True
+                        self.focused_widget = node
+                    for c in node.children:
+                        restore_focus(c)
+                self.focused_widget = None
+                restore_focus(self.root)
+            
+        if self.root:
+            # 1. Resolve CSS
+            self.root.resolve_styles(self.stylesheet)
+            # 2. Assign root X/Y
+            self.root.x = 0
+            self.root.y = 0
+            # 3. Calculate Layout
+            w, h = self._last_size
+            self.root.calculate_layout(w, h)
+            # 4. Render Layout
+            self.root.render(self)
+        else:
+            self.write(f"Casca UI - Press 'q' to exit.\\n Terminal size: {self._last_size}")
+
+def run_app(widget, css=""):
+    """A convenience wrapper to run a single widget without subclassing App."""
+    class WrapperApp(App):
+        def __init__(self):
+            super().__init__()
+            self.css = css
+        def build_ui(self):
+            return widget
+    
+    WrapperApp().run()

casca-0.1.0/casca/core/events.py

@@ -0,0 +1,18 @@
+from dataclasses import dataclass
+
+@dataclass
+class KeyEvent:
+    key: str
+    is_printable: bool
+
+@dataclass
+class ResizeEvent:
+    width: int
+    height: int
+
+@dataclass
+class MouseEvent:
+    x: int
+    y: int
+    button: int
+    pressed: bool

casca-0.1.0/casca/core/terminal.py

@@ -0,0 +1,48 @@
+import os
+import sys
+import tty
+import termios
+
+from .ansi import ALT_SCREEN_ON, ALT_SCREEN_OFF, HIDE_CURSOR, SHOW_CURSOR, MOUSE_ON, MOUSE_OFF
+
+
+class RawTerminal:
+    """
+    Context manager to safely put the terminal into raw mode,
+    switch to the alternate screen buffer, and hide the cursor.
+    """
+    def __init__(self):
+        self.fd = sys.stdin.fileno()
+        self.old_settings = None
+
+    def __enter__(self):
+        # Save old terminal settings
+        self.old_settings = termios.tcgetattr(self.fd)
+        
+        # Set raw mode to read characters immediately
+        tty.setraw(self.fd)
+        
+        # Switch to alternate screen, hide cursor, enable mouse tracking
+        sys.stdout.write(ALT_SCREEN_ON)
+        sys.stdout.write(HIDE_CURSOR)
+        sys.stdout.write(MOUSE_ON)
+        sys.stdout.flush()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        # Restore normal screen, show cursor, disable mouse
+        sys.stdout.write(MOUSE_OFF)
+        sys.stdout.write(ALT_SCREEN_OFF)
+        sys.stdout.write(SHOW_CURSOR)
+        sys.stdout.flush()
+        
+        # Restore terminal settings
+        termios.tcsetattr(self.fd, termios.TCSADRAIN, self.old_settings)
+
+def get_terminal_size() -> tuple[int, int]:
+    """Returns (width, height) of the current terminal."""
+    try:
+        size = os.get_terminal_size()
+        return size.columns, size.lines
+    except OSError:
+        return 80, 24

casca-0.1.0/casca/dom/node.py

@@ -0,0 +1,184 @@
+from typing import Optional, List
+from ..core.ansi import Color, BackColor, color, move_cursor, BOLD, FAINT, ITALIC, UNDERLINE, RESET
+from ..core.events import KeyEvent, MouseEvent
+
+class Widget:
+    """The base class for all UI elements (DOM Node)."""
+    
+    tag = 'widget'
+
+    def __init__(self, *children, id: str = "", classes: str = "", **props):
+        self.children: List['Widget'] = list(children)
+        self.id = id
+        self.classes = classes.split() if classes else []
+        self.props = props
+        
+        # Layout properties (calculated)
+        self.x = 0
+        self.y = 0
+        self.width = 0
+        self.height = 0
+        self.content_width = 0
+        self.content_height = 0
+        
+        # Resolved styles (from CSS)
+        self.style = {}
+        
+        # State
+        self.focused = False
+
+    def resolve_styles(self, stylesheet: dict):
+        from ..style.css import get_style_for_node
+        self.style = get_style_for_node(self.id, self.classes, self.tag, stylesheet)
+        
+        # Recursively resolve styles for children
+        for child in self.children:
+            child.resolve_styles(stylesheet)
+            
+    def calculate_layout(self, available_width: int, available_height: int) -> tuple[int, int]:
+        """Base layout logic Flow (stacking). Returns tuple of (width_used, height_used)."""
+        
+        # Apply padding and border calculations
+        padding = int(self.style.get('padding', 0))
+        margin = int(self.style.get('margin', 0))
+        border_width = 1 if 'border' in self.style else 0
+        
+        # Width priority: Direct property -> Inline style -> Available parent width
+        self.width = self.props.get('width', int(self.style.get('width', available_width)))
+        
+        # Content layout logic (stack children vertically by default)
+        current_y = padding + border_width
+        max_child_width = 0
+        
+        for child in self.children:
+            child.x = self.x + padding + border_width
+            child.y = self.y + current_y
+            
+            # The children can occupy the inner space
+            inner_avail_width = max(0, self.width - 2*(padding + border_width))
+            
+            child_w, child_h = child.calculate_layout(inner_avail_width, available_height - current_y)
+            current_y += child_h
+            max_child_width = max(max_child_width, child_w)
+            
+        self.content_width = max_child_width
+        self.content_height = current_y - (padding + border_width)
+        
+        # Total height used by this widget including padding, border and margin
+        min_height = padding * 2 + border_width * 2
+        
+        # If height is strictly set
+        set_height = self.props.get('height') or self.style.get('height')
+        if set_height:
+            self.height = int(set_height)
+        else:
+            self.height = self.content_height + min_height
+            
+        return self.width + margin * 2, self.height + margin * 2
+
+    def apply_style(self, app):
+        """Applies the current widget's computed style and background to the terminal output."""
+        app.write(RESET)
+        border_style = self.style.get('border', 'none')
+        fg_color = self.style.get('color', 'DEFAULT').upper()
+        bg_color = self.style.get('background', 'DEFAULT').upper()
+        
+        fg = getattr(Color, fg_color, Color.DEFAULT)
+        bg = getattr(BackColor, bg_color, BackColor.DEFAULT)
+        app.write(color(fg, bg))
+
+        # Apply text styling
+        if self.style.get('font-weight') == 'bold': app.write(BOLD)
+        if self.style.get('font-style') == 'italic': app.write(ITALIC)
+        if self.style.get('text-decoration') == 'underline': app.write(UNDERLINE)
+        if 'opacity' in self.style and float(self.style['opacity']) < 1.0: app.write(FAINT)
+
+    def render(self, app):
+        """Draws the widget to the app render buffer."""
+        self.apply_style(app)
+        
+        # Draw background fill if applicable
+        if 'background' in self.style:
+            for r in range(self.height):
+                app.draw_text(self.x + 1, self.y + r + 1, " " * self.width)
+            self.apply_style(app)
+
+        # Draw border
+        if self.style.get('border', 'none') != 'none':
+            self._draw_border(app)
+            
+        # Draw own content
+        self.render_content(app)
+        
+        # Draw children
+        for child in(self.children):
+            child.render(app)
+            # Reattach own style so subsequent children/parents don't get reset
+            self.apply_style(app)
+            
+        app.write(RESET)
+        
+    def render_content(self, app):
+        """Override to implement specific widget text / drawing logic."""
+        pass
+            
+    def _draw_border(self, app):
+        border_char = self.style.get('border-char', '+') if self.style.get('border') == 'ascii' else '█'
+        # Top and bottom
+        for r in (0, self.height - 1):
+            if r >= 0 and self.width > 0:
+                app.draw_text(self.x + 1, self.y + r + 1, border_char * self.width)
+                
+        # Sides
+        for r in range(1, self.height - 1):
+            if self.width > 0:
+                app.draw_text(self.x + 1, self.y + r + 1, border_char)
+                if self.width > 1:
+                    app.draw_text(self.x + self.width, self.y + r + 1, border_char)
+                    
+    def handle_input(self, event: KeyEvent) -> bool:
+        """
+        Returns True if the event was consumed, preventing bubbling.
+        Passes input down the tree.
+        """
+        for child in reversed(self.children):
+            if child.handle_input(event):
+                return True
+        return False
+        
+    def handle_mouse(self, event: MouseEvent, app) -> bool:
+        """Passes mouse events down if they fall within bounds."""
+        # Terminal coordinates are typically 1-based, and our widget coordinates (x,y) 
+        # may be 0-based logically, but rendered 1-based. 
+        # Actually our calculate_layout produces 0-based x, y. And move_cursor adds 1.
+        # Let's align on 0-based checking. The event has 1-based x,y.
+        term_x = event.x - 1
+        term_y = event.y - 1
+
+        if self.x <= term_x < self.x + self.width and self.y <= term_y < self.y + self.height:
+            # Propagate to children first (highest z-index effectively)
+            for child in reversed(self.children):
+                if child.handle_mouse(event, app):
+                    return True
+                    
+            if event.pressed and self.tag in ('input', 'button', 'checkbox'):
+                if app.focused_widget and app.focused_widget != self:
+                    app.focused_widget.focused = False
+                app.focused_widget = self
+                self.focused = True
+                if self.id:
+                    app.focused_id = self.id
+
+            # If kids didn't handle it, try handling it ourselves
+            handled = self.on_mouse(event) or (event.pressed and self.tag in ('input', 'button', 'checkbox'))
+            
+            # Special case for scroll wheel in bounds but not handled
+            if not handled and event.button in (64, 65):
+                return getattr(self, 'handle_wheel', lambda e, a: False)(event, app)
+                
+            return handled
+        return False
+
+    def on_mouse(self, event: MouseEvent) -> bool:
+        """Override to implement specific widget mouse logic."""
+        return False

casca-0.1.0/casca/style/css.py

@@ -0,0 +1,57 @@
+import re
+from typing import Dict, Any
+
+def parse_css(css_string: str) -> Dict[str, Dict[str, str]]:
+    """
+    Extremely lightweight CSS parser.
+    Supports basic classes (.cls), IDs (#id), and Element (tag) selectors.
+    Returns: { '.btn': {'color': 'red', 'padding': '1'}, ... }
+    """
+    stylesheet = {}
+    
+    # Remove comments
+    css_string = re.sub(r'/\*.*?\*/', '', css_string, flags=re.DOTALL)
+    
+    # Find all blocks: selector { rules }
+    blocks = re.findall(r'([^{]+)\{([^}]+)\}', css_string)
+    
+    for selector_group, rules_text in blocks:
+        selectors = [s.strip() for s in selector_group.split(',')]
+        
+        rules = {}
+        for rule in rules_text.split(';'):
+            rule = rule.strip()
+            if not rule:
+                continue
+            if ':' in rule:
+                key, value = rule.split(':', 1)
+                rules[key.strip()] = value.strip()
+                
+        for selector in selectors:
+            if selector not in stylesheet:
+                stylesheet[selector] = {}
+            stylesheet[selector].update(rules)
+            
+    return stylesheet
+
+def get_style_for_node(node_id: str, classes: list[str], tag: str, stylesheet: dict) -> dict:
+    """Resolve styles for a given node in order of specificity: tag -> class -> id"""
+    style = {}
+    
+    # 1. Tag
+    if tag in stylesheet:
+        style.update(stylesheet[tag])
+        
+    # 2. Classes
+    for cls in classes:
+        cls_sel = f".{cls}"
+        if cls_sel in stylesheet:
+            style.update(stylesheet[cls_sel])
+            
+    # 3. ID
+    if node_id:
+        id_sel = f"#{node_id}"
+        if id_sel in stylesheet:
+            style.update(stylesheet[id_sel])
+            
+    return style

casca-0.1.0/casca.egg-info/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: casca
+Version: 0.1.0
+Summary: Native Python CLI UI library with CSS-like styling
+Author-email: Abdallah <abdalla.zain2004@gmail.com>
+License: MIT
+Keywords: tui,cli,terminal,ui,css,python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: chatbot
+Requires-Dist: groq>=0.20.0; extra == "chatbot"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.8.0; extra == "docs"
+Dynamic: license-file
+
+# Casca
+
+Casca is a lightweight, native Python TUI library with a DOM-like widget tree and CSS-style theming.
+
+## Features
+
+- Zero core dependencies (standard library runtime)
+- Declarative widgets (`Container`, `Label`, `Input`, `Button`, `Card`, `Header`, `ScrollView`)
+- CSS-like style parsing and cascade
+- Keyboard and mouse event handling in raw terminal mode
+- Real examples including login screen, dashboard, and Groq chatbot
+
+## Quick Start
+
+```python
+from casca import Container, Label, run_app
+
+CSS = """
+#root {
+    padding: 1;
+    border: ascii;
+}
+"""
+
+
+
+ui_tree = Container(
+    Label("Hello from Casca"),
+    id="root",
+)
+
+if __name__ == "__main__":
+    run_app(ui_tree, css=CSS)
+```
+
+## Run Use Cases
+
+```bash
+python3 -m use_cases.login_screen
+python3 -m use_cases.dashboard
+python3 -m use_cases.chatbot
+```
+
+`use_cases.chatbot` requires `groq` and a `GROQ_API_KEY`.
+
+
+## Project Layout
+
+- `casca/`: core library
+- `use_cases/`: real apps built with Casca
+- `examples/`: smaller demos
+- `docs/`: MkDocs content
+
+## License
+
+MIT

casca-0.1.0/casca.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+casca/__init__.py
+casca.egg-info/PKG-INFO
+casca.egg-info/SOURCES.txt
+casca.egg-info/dependency_links.txt
+casca.egg-info/requires.txt
+casca.egg-info/top_level.txt
+casca/components/__init__.py
+casca/components/base.py
+casca/components/forms.py
+casca/components/panels.py
+casca/components/scroll.py
+casca/core/__init__.py
+casca/core/ansi.py
+casca/core/app.py
+casca/core/events.py
+casca/core/terminal.py
+casca/dom/__init__.py
+casca/dom/node.py
+casca/style/__init__.py
+casca/style/css.py
+tests/test_imports.py

casca-0.1.0/casca.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

casca-0.1.0/casca.egg-info/requires.txt

@@ -0,0 +1,8 @@
+
+[chatbot]
+groq>=0.20.0
+
+[docs]
+mkdocs>=1.6.0
+mkdocs-material>=9.5.0
+pymdown-extensions>=10.8.0

casca-0.1.0/casca.egg-info/top_level.txt

@@ -0,0 +1 @@
+casca

casca-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "casca"
+version = "0.1.0"
+description = "Native Python CLI UI library with CSS-like styling"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Abdallah", email = "abdalla.zain2004@gmail.com" }
+]
+keywords = ["tui", "cli", "terminal", "ui", "css", "python"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Topic :: Software Development :: User Interfaces"
+]
+
+[project.optional-dependencies]
+chatbot = ["groq>=0.20.0"]
+docs = [
+  "mkdocs>=1.6.0",
+  "mkdocs-material>=9.5.0",
+  "pymdown-extensions>=10.8.0"
+]
+
+[tool.setuptools]
+packages = ["casca", "casca.core", "casca.dom", "casca.style", "casca.components"]

casca-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

casca-0.1.0/tests/test_imports.py

@@ -0,0 +1,12 @@
+from casca import App, Container, Label, Button, Input, Checkbox, Card, Header
+
+
+def test_core_imports_exist():
+    assert App is not None
+    assert Container is not None
+    assert Label is not None
+    assert Button is not None
+    assert Input is not None
+    assert Checkbox is not None
+    assert Card is not None
+    assert Header is not None