brickflowui 0.1.0__tar.gz

brickflowui-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.pytest_cache/
+.tmp/
+.venv/
+build/
+dist/
+frontend/node_modules/
+*.egg-info/
+*.pyc
+__pycache__/
+tests/_tmp_cli/
+frontend/tsc_errors.txt

brickflowui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrickflowUI 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.

brickflowui-0.1.0/PKG-INFO

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: brickflowui
+Version: 0.1.0
+Summary: A Databricks-first Python UI framework for building secure dashboards, portals, and web apps with pure Python.
+Project-URL: Homepage, https://github.com/brickflowui/bricksflowui
+Project-URL: Documentation, https://github.com/brickflowui/bricksflowui/tree/main/docs
+Project-URL: Repository, https://github.com/brickflowui/bricksflowui
+Project-URL: Issues, https://github.com/brickflowui/bricksflowui/issues
+Author: BrickflowUI Contributors
+License: MIT License
+        
+        Copyright (c) 2026 BrickflowUI 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.
+License-File: LICENSE
+Keywords: dashboard,databricks,fastapi,portal,python-framework,ui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: starlette>=0.37.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: all
+Requires-Dist: bricksflowui[databricks,dev,viz]; extra == 'all'
+Provides-Extra: databricks
+Requires-Dist: databricks-sdk>=0.20.0; extra == 'databricks'
+Requires-Dist: databricks-sql-connector>=3.0.0; extra == 'databricks'
+Requires-Dist: pandas>=2.0.0; extra == 'databricks'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Provides-Extra: viz
+Requires-Dist: plotly>=5.0.0; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# BricksFlowUI
+
+> Canonical package name: `bricksflowui`
+>
+> Install with:
+>
+> ```bash
+> pip install bricksflowui
+> ```
+>
+> Import with:
+>
+> ```python
+> import brickflowui as db
+> ```
+>
+> Start here:
+> - [Getting Started](./docs/GETTING_STARTED.md)
+> - [Build Guide](./docs/BUILD.md)
+> - [API Reference](./docs/API_REFERENCE.md)
+> - [Theming](./docs/THEMING.md)
+> - [Publishing](./docs/PUBLISHING.md)
+
+## Release Notes
+
+- PyPI package name is now `bricksflowui`
+- CLI commands supported: `brickflowui` and `bricksflowui`
+- Standard Python import remains `brickflowui`
+- Source distributions and wheels include bundled frontend assets plus docs/examples
+
+> **Databricks-first, React-style Python UI library** for building composable, production-ready Databricks Apps — without writing a single line of JavaScript.
+
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+---
+
+## What is BricksFlowUI?
+
+BricksFlowUI lets data engineers build beautiful, interactive Databricks Apps in **pure Python**. It ships a pre-built React frontend and communicates over WebSocket, so you get:
+
+- ⚡ **No full-script reruns** — only changed components re-render (unlike Streamlit)
+- 🧩 **React-style component model** — composable functions, hooks, one-way data flow
+- 🔒 **Databricks-native** — reads `DATABRICKS_APP_PORT`, Unity Catalog helpers, SQL warehouse wrappers
+- 🎨 **Beautiful dark theme** — Databricks-inspired design system, no CSS required
+
+---
+
+## Quick Start
+
+```bash
+pip install bricksflowui
+
+# Scaffold a new app
+brickflowui new my_app
+cd my_app
+
+# Run locally
+brickflowui dev
+# → open http://localhost:8050
+```
+
+Or manually:
+
+```python
+# app.py
+import brickflowui as db
+
+app = db.App(title="My Databricks App")
+
+@app.page("/", title="Home", icon="Home")
+def home():
+    count, set_count = db.use_state(0)
+    return db.Column([
+        db.Text("Counter", variant="h1"),
+        db.Text(f"Count: {count}", variant="h3"),
+        db.Button("Increment", on_click=lambda: set_count(count + 1)),
+    ], padding=6)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+---
+
+## Core Concepts
+
+### Components
+
+Every UI element is a plain Python function returning a `VNode`:
+
+```python
+import brickflowui as db
+
+# Layout
+db.Column(children, gap=4, padding=6)
+db.Row(children, gap=2, justify="between")
+db.Grid(children, cols=3, gap=4)
+db.Card(children, title="My Card")
+
+# Typography
+db.Text("Hello!", variant="h1")   # h1, h2, h3, h4, body, caption, label, code
+
+# Controls
+db.Button("Click me", on_click=handler, variant="primary")
+db.Input(name="q", label="Search", on_change=setter)
+db.Select(name="w", options=[{"label": "A", "value": "a"}], on_change=setter)
+db.Checkbox(name="x", label="Enable", on_change=setter)
+db.Toggle(name="y", label="Dark mode", on_change=setter)
+db.Slider(name="s", min=0, max=100, on_change=setter)
+
+# Data
+db.Table(data=rows, columns=[{"key": "id", "label": "ID"}], pagination=20)
+db.Badge("Active", color="green")
+db.Alert("Something went wrong", type="error")
+db.Progress(value=65, max=100)
+db.Stat(label="Queries", value="248K", delta="+12%", delta_type="increase")
+
+# Charts
+db.AreaChart(data=rows, x_key="date", y_keys=["value"], colors=["#FF3621"])
+db.BarChart(data=rows, x_key="category", y_keys=["count"])
+db.LineChart(data=rows, x_key="day", y_keys=["metric"])
+db.DonutChart(data=rows, value_key="count", label_key="name")
+
+# Navigation
+db.Tabs([db.TabItem("Tab A", [db.Text("Content A")]), ...])
+db.Sidebar([db.NavItem("Home", "/", icon="Home"), ...], brand_name="My App")
+db.Modal(visible=True, title="Confirm", children=[...], on_close=handler)
+
+# Forms
+db.Form(action="/api/submit", success_redirect="/", children=[
+    db.Input(name="username", label="Username"),
+    db.Button("Submit", html_type="submit"),
+])
+
+# Databricks-specific
+db.CatalogBrowser(on_select=handler)
+db.WarehouseSelector(on_select=handler)
+db.JobTrigger(job_id="123", label="Run Pipeline")
+```
+
+### State (Hooks)
+
+```python
+@app.page("/")
+def my_page():
+    count, set_count = db.use_state(0)          # local state
+    data = db.use_memo(load_data, deps=[count])  # memoized compute
+    db.use_effect(lambda: print("mounted"), [])  # side effects
+    theme = db.use_context("theme")              # session context
+
+    return db.Button(str(count), on_click=lambda: set_count(count + 1))
+```
+
+### Multi-page Apps
+
+```python
+app = db.App(title="Ops Hub")
+
+@app.page("/", title="Dashboard", icon="LayoutDashboard")
+def dashboard(): ...
+
+@app.page("/tables", title="Tables", icon="Database")
+def tables(): ...
+
+@app.page("/settings", title="Settings", icon="Settings")
+def settings(): ...
+```
+
+### Auth And Access Control
+
+```python
+import brickflowui as db
+
+app = db.App(
+    title="Ops Hub",
+    auth_mode="hybrid",  # "app", "user", or "hybrid"
+    auth_provider=db.HeaderAuthProvider(),
+)
+
+@app.page("/", title="Home")
+def home():
+    principal = db.current_principal()
+    return db.Text(f"Hello {principal.display_name or principal.subject}")
+
+@app.page("/admin", title="Admin", access="user", roles=["admin"])
+def admin():
+    user = db.require_role("admin")
+    return db.Text(f"Welcome, {user.subject}")
+
+@app.route("/api/profile", methods=["GET"], access="user")
+async def profile():
+    user = db.require_auth()
+    return {"user": user.subject, "roles": list(user.roles)}
+```
+
+`access` supports:
+
+- `public` — anyone can access it
+- `authenticated` — any authenticated principal
+- `user` — requires a signed-in user identity
+- `app` — restricted to the shared application identity
+
+### Branding And Themes
+
+```python
+app = db.App(theme="branding.yaml")
+```
+
+Example `branding.yaml`:
+
+```yaml
+branding:
+  title: "Acme Ops Portal"
+  logo: "/static/acme-logo.svg"
+  favicon: "/static/acme-favicon.ico"
+
+colors:
+  primary: "#FF5F2E"
+  primary_hover: "#D9481C"
+  background: "#F7F7F5"
+  surface: "#FFFFFF"
+  text: "#18181B"
+  text_muted: "#71717A"
+  border: "#E4E4E7"
+
+typography:
+  font_family: "'IBM Plex Sans', sans-serif"
+  base_size: "15px"
+
+spacing:
+  unit: "6px"
+
+borders:
+  radius: "14px"
+```
+
+Supported theme model sections:
+
+- `branding`: `title`, `logo`, `favicon`
+- `colors`: `primary`, `primary_hover`, `background`, `surface`, `text`, `text_muted`, `border`, `success`, `warning`, `error`, `link`
+- `typography`: `font_family`, `font_mono`, `base_size`
+- `spacing`: `unit`
+- `borders`: `radius`
+
+You can also keep using the lower-level internal keys like `primary-hover`, `bg`, `text-muted`, `sans`, and `base-size` if you prefer.
+
+### Custom API Routes
+
+```python
+@app.route("/api/submit", methods=["POST"])
+async def submit_handler():
+    from fastapi.responses import JSONResponse
+    return JSONResponse({"status": "ok"})
+```
+
+---
+
+## Databricks Integration
+
+### SQL Queries
+
+```python
+from brickflowui.databricks import sql
+
+# Returns a pandas DataFrame
+df = sql.query("SELECT * FROM catalog.schema.table LIMIT 100")
+
+# Returns list[dict] (for db.Table component)
+rows = sql.query_to_records("SELECT id, name FROM my_table")
+return db.Table(data=rows)
+```
+
+Set environment variables (or use `app.yaml`):
+
+```env
+DATABRICKS_HOST=https://adb-xxx.azuredatabricks.net
+DATABRICKS_TOKEN=dapiXXXXXXXX
+DATABRICKS_WAREHOUSE_ID=your-warehouse-id
+```
+
+### Unity Catalog
+
+```python
+from brickflowui.databricks import uc
+
+catalogs = uc.list_catalogs()
+schemas  = uc.list_schemas("main")
+tables   = uc.list_tables("main", "gold")
+rows     = uc.get_table("main", "gold", "fact_orders", limit=50)
+```
+
+---
+
+## Deploying to Databricks Apps
+
+### `app.yaml`
+
+```yaml
+command:
+  - python
+  - app.py
+
+env:
+  - name: DATABRICKS_WAREHOUSE_ID
+    value: your-warehouse-id
+```
+
+Then in the Databricks workspace:
+1. Create a new Databricks App
+2. Upload your project as a ZIP (include `app.py`, `app.yaml`, `requirements.txt`)
+3. The app binds to `DATABRICKS_APP_PORT` automatically
+
+### `requirements.txt`
+
+```text
+bricksflowui>=0.1.0
+# bricksflowui[databricks]  # for SQL + Unity Catalog
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `brickflowui new <name>` | Scaffold a new app |
+| `brickflowui dev` | Run local dev server (hot reload) |
+
+---
+
+## Project Structure
+
+```text
+brickflowui/
+├── __init__.py          # Public API
+├── app.py               # App class
+├── vdom.py              # Virtual DOM + diff algorithm
+├── state.py             # Hooks (use_state, use_effect, use_memo)
+├── components.py        # All component primitives
+├── server.py            # FastAPI ASGI + WebSocket server
+├── cli/
+│   ├── main.py          # CLI (typer)
+│   └── templates/       # App scaffolding templates
+├── databricks/
+│   ├── env.py           # DATABRICKS_* env helpers
+│   ├── sql.py           # SQL connector wrappers
+│   └── uc.py            # Unity Catalog helpers
+└── frontend/
+    └── dist/            # Pre-built React bundle (served automatically)
+
+examples/
+├── counter/             # Minimal Counter example
+└── demo_app/            # Full multi-page dashboard demo
+    ├── app.py
+    ├── app.yaml
+    └── requirements.txt
+```
+
+---
+
+## Architecture
+
+```
+Python App (app.py)
+    │
+    │  Component tree (VNode)
+    ▼
+BrickflowUI Runtime
+    │  FastAPI ASGI Server
+    │  WS /events   ──── JSON patches ────▶  React Frontend
+    │  GET /         ◀─── HTML shell ──────
+    │  GET /static/* ◀─── React bundle ────
+    │
+    ▼
+Databricks Runtime
+    (DATABRICKS_APP_PORT, SQL warehouse, Unity Catalog)
+```
+
+---
+
+## License
+
+MIT © BrickflowUI Contributors