pycascadeui 2.1.0

Redux-inspired UI framework for discord.py

Build predictable, state-driven interfaces with discord.py.
Design complex interactive systems with centralized state, composable UI patterns, and a clear data flow.

Read the Docs

---

Why CascadeUI

Interactive Discord UIs become difficult to manage as they grow. State is scattered across callbacks, views become tightly coupled, and behavior becomes harder to reason about.

CascadeUI introduces structure:

• Centralized state instead of scattered variables
• Predictable updates through dispatched actions
• Clear separation between logic and presentation
• Reusable UI patterns instead of one-off implementations
• Built-in solutions for persistence, navigation, and state history

This approach scales from simple panels to full application-style interfaces.

---

Architecture

CascadeUI follows a unidirectional data flow model:

User interaction -> dispatch(action)
  -> middleware
  -> reducer (state update)
  -> subscribers notified
  -> views re-render

All state lives in a single store. Actions describe what happened. Reducers define how state changes. Views subscribe to relevant state and update automatically.

---

When to Use

CascadeUI is designed for building complex interfaces that go beyond simple interactions.

A powerful, fully featured UI library should be leveraged when your app requires:

• Shared state across multiple views
• Real data and message persistence
• Maintainable complex interaction logic
• Message lifecycle and ownership control
• Consistent UI composition
• Cross-view reactivity
• Multi-step flows and validation

It may be unnecessary for small or simple interfaces.

---

Features

For full details, see the official documentation.

State and Data Flow

• Centralized store with dispatch and reducer cycle
• Custom reducers via @cascade_reducer decorator with automatic deep copy
• Action batching for grouped, atomic updates
• Computed state and derived values
• Selector-based subscriptions for targeted re-renders
• Cross-view reactivity: dispatch from any view, all subscribers update instantly
• Middleware pipeline for logging, persistence, and transformation
• Event hooks for lifecycle observation and side effects

Views and Interaction Patterns

• Layout-based V2 system for structured interfaces
• Full support for traditional discord.py Views (V1)
• Pre-built patterns: tabs, wizards, forms, pagination
• Navigation stack with push, pop, and replace
• Session limiting per user, guild, or globally with replace or reject policies
• Multi-user access control via allowed_users with participant-aware session limiting
• Interaction ownership control (owner-only by default)
• Auto-defer for slow callbacks and interaction serialization for rapid input
• Theming with per-view overrides and V2 accent colors

Components and Composition

• Stateful buttons, selects, and modals with state integration
• V2 layout helpers: card(), key_value(), alert(), action_section(), and more
• Built-in form system with validation and per-field error handling
• Component wrappers: loading states, confirmation dialogs, cooldowns

Persistence and Infrastructure

• Persistent views that survive bot restarts with automatic message re-attachment
• State persistence backends: JSON, SQLite, Redis
• Undo and redo via snapshot-based state history
• Scoped state isolation (user, guild, global)
• Developer tools for live state inspection and debugging

---

Showcase

Dashboard Pattern

Structured, multi-section interfaces with tab-based navigation and composable layouts.

---

Navigation and Flow

Navigate between views without sending new messages. Maintain context across layered interfaces.

---

State History (Undo/Redo)

Snapshot-based state history per session with built-in undo and redo support.

---

Cross-View Reactivity

Dispatch actions from any view and update all subscribers instantly across the interface.

---

Lifecycle Control

Control active sessions per user, guild, or globally with automatic cleanup and replacement policies.

class DashboardView(TabLayoutView):
    session_limit = 1               # Only one open at a time
    session_scope = "user_guild"    # Per user per guild
    session_policy = "replace"      # Exit the old one, open the new one

---

Persistence and Continuity

Persist views and state across restarts with automatic restoration.

# Enable persistence once in your bot's setup_hook:
async def setup_hook(self):
    await setup_persistence(bot=self, backend=SQLiteBackend("cascadeui.db"))

---

Dynamic Pagination

Generate paginated interfaces from raw data with built-in navigation and formatting helpers.

from cascadeui import PaginatedLayoutView

def format_page(items):
    lines = [f"**{item['name']}** | {item['rarity']} | {item['value']}g" for item in items]
    return [Container(
        TextDisplay("## Inventory"),
        Separator(),
        TextDisplay("\n".join(lines)),
        accent_colour=discord.Color.blue(),
    )]

view = await PaginatedLayoutView.from_data(
    items=all_items,
    per_page=4,
    formatter=format_page,
    context=ctx,
)
await view.send()

---

Forms and Validation

Define structured input flows with automatic validation and per-field error handling.

from cascadeui import FormLayoutView, choices, card, key_value, divider

class RegistrationForm(FormLayoutView):
    session_limit = 1

    def __init__(self, *args, **kwargs):
        fields = [
            {
                "id": "role",
                "label": "Role",
                "type": "select",
                "required": True,
                "options": [
                    {"label": "Developer", "value": "developer"},
                    {"label": "Designer", "value": "designer"},
                    {"label": "Manager", "value": "manager"},
                ],
                "validators": [choices(["developer", "designer", "manager"])],
            },
            {
                "id": "terms",
                "label": "Accept Terms of Service",
                "type": "boolean",
                "required": True,
            },
        ]

        super().__init__(
            *args,
            title="Registration",
            fields=fields,
            on_submit=self.handle_submit,
            **kwargs,
        )

    def _rebuild_display(self):
        """Override display with V2 helpers for a richer presentation."""
        v = self.values
        action_rows = [c for c in self.children if isinstance(c, ActionRow)]
        self.clear_items()

        self.add_item(card(
            "## Registration Form",
            key_value({"Role": v.get("role", "-").title() if v.get("role") else "-"}),
            divider(),
            TextDisplay(f"Terms: {'Accepted' if v.get('terms') else 'Pending'}"),
        ))

        for row in action_rows:
            self.add_item(row)

---

Developer Tools

Live state inspection and debugging with a tabbed inspector view. Add one line to your bot.

from cascadeui.devtools import DevToolsCog

# In your bot's setup_hook:
await bot.add_cog(DevToolsCog(bot))

---

V1 Components

CascadeUI supports traditional discord.py Views and embeds.

Use V1 when you need:

• Embed-specific features such as fields or timestamps
• Simpler layouts without containers

All core features such as navigation, persistence, and undo/redo are supported.

---

Examples

The documentation includes full implementations demonstrating practical usage:

• Dashboards and control panels
• Settings systems
• Pagination
• Forms and wizards
• Persistent views
• Ticket systems
• Multi-user games

---

Getting Started

pip install pycascadeui

Optional dependencies:

pip install pycascadeui[sqlite]
pip install pycascadeui[redis]

Requirements:

• Python 3.10+
• discord.py 2.7+

---

Documentation

• https://hollowthesilver.github.io/CascadeUI/

---

Support

• Discord: https://discord.com/invite/9Xj68BpKRb
• Issues: https://github.com/HollowTheSilver/CascadeUI/issues

---

Development

git clone https://github.com/HollowTheSilver/CascadeUI.git
cd CascadeUI
pip install -e ".[dev]"

pytest tests/ -v
black cascadeui/
isort cascadeui/

---

MIT License