Metadata-Version: 2.4
Name: faststrap-preview-studio
Version: 0.9.0
Summary: Interactive Component Studio & Live Documentation Preview Engine for FastStrap + FastHTML
Author: FastStrap Team
License: MIT
Keywords: fasthtml,faststrap,bootstrap,htmx,ui,components,preview,playground
Classifier: Development Status :: 4 - Beta
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 :: Software Development :: User Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-fasthtml>=0.14.13
Requires-Dist: faststrap>=0.10.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: starlette>=0.37.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# ⚡ FastStrap Preview Studio

Interactive real-time component studio, live playground, and documentation preview engine for **FastStrap** + **FastHTML**.

Built primarily as a local learning tool: run the Studio on your own machine, explore real FastStrap examples, and use the code sandbox locally. The Studio shell, Bootstrap/FastStrap assets, and FastHTML's base browser runtimes are served from the local installation. Optional rich renderers (KaTeX, Mermaid, Chart.js, Plotly, and GSAP) still load from CDNs when their components are previewed, so those specific examples need internet access.

---

<p align="center">
  <img src="screenshots/faststrap_studio_dark.png" alt="FastStrap Preview Studio - Dark Mode" width="100%" />
</p>

<p align="center">
  <img src="screenshots/faststrap_studio_ligh1.png" alt="FastStrap Preview Studio - Light Mode Gallery" width="49%" />
  <img src="screenshots/faststrap_studio_btn_light.png" alt="FastStrap Preview Studio - Interactive Controls" width="49%" />
</p>

---

## 🌟 Key Features

* **⚡ Local-First & Offline Core**: The Studio and its standard component examples run locally without shared cloud compute. Optional rich renderers may need internet access.
* **📦 Explicit Import Guidance**: Every component in the Studio displays an exact, 1-click copyable import statement (`from faststrap import ...` or `from faststrap.presets import ...`) alongside runnable code snippets.
* **🎨 Interactive Canvas & Auto-Height**: Smooth viewport switcher (Mobile 375px, Tablet 768px, Laptop 1024px, Desktop 100%), background modes (Dark grid, Light grid, Checkerboard, Transparent), and adaptive canvas auto-height.
* **🔧 Type-Safe Interactive Controls**: Real-time debounced parameter knobs for variants, sizes, shapes, numbers, and boolean toggles.
* **📋 Dynamic Props Reference**: Built-in parameter tables with argument types, defaults, and descriptions for **86 components**, including FastStrap v0.10.0's mobile, collection, and responsive table components.
* **🔗 MkDocs Documentation Embeds**: Dedicated `/embed/{component}` endpoint for clean iframe embedding in documentation sites.
* **🧪 Interactive HTMX Sandbox**: Real-time interactive demos for `ActiveSearch`, `LoadingButton`, `EmailValidation`, and `DataTable` with simulated network latency.
* **🧪 Trusted Local Code Playground**: Run complete FastHTML examples on your own machine. Keep the Studio loopback-only; hosted documentation mode can disable the sandbox routes entirely.

---

## 🚀 Running Locally (Single Command)

### Install From Source

```bash
# 1. Clone repo
git clone https://github.com/Faststrap-org/FastStrap-Studio.git
cd FastStrap-Studio

# 2. Create and activate a virtual environment, then install the Studio
python -m venv .venv
# Windows PowerShell: .venv\Scripts\Activate.ps1
# macOS/Linux: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

# 3. Start preview server
python main.py
```

Open `http://127.0.0.1:8080` in your browser. A PyPI installation command will be
added after the Studio package has actually been published.

Environment variables supported:
* `PORT`: Server port (default: `8080`)
* `HOST`: Bind host (default: `127.0.0.1`, local machine only)
* `RELOAD`: Enable hot-reloading (e.g. `RELOAD=true`)
* `STUDIO_ENABLE_ARBITRARY_EXEC`: Defaults to `true` for the local trusted-user workflow.
  This allows examples to use normal Python imports and application code. It is not a
  security sandbox; do not expose this mode to untrusted users. Setting it to `false`
  applies AST restrictions, but is not process or container isolation.
* `STUDIO_ENABLE_SANDBOX`: Defaults to `true`; set to `false` to omit `/sandbox/*` routes
  entirely when hosting only the curated component preview endpoints for documentation.

The Studio's local arbitrary-code sandbox is intentional: it runs code on the user's own
machine so complete FastHTML examples work without shared cloud execution. Base frontend
scripts are vendored in `faststrap_studio/static/vendor/`; their upstream versions and
licenses are listed in `faststrap_studio/static/vendor/README.md`. For a hosted
docs integration, disable the sandbox and expose only curated `/embed/*` and `/preview/*`
routes. The `STUDIO_ENABLE_ARBITRARY_EXEC=false` mode applies AST restrictions but is not
a substitute for process/container isolation and should not be presented as a secure
public multi-user execution service. Keep the default bind address on loopback; setting
`HOST=0.0.0.0` exposes the local server to the network.

---

## 💡 Using Components in Your FastHTML App

Every component page in Studio provides a copyable import chip:

```python
# 1. Import from FastStrap
from faststrap import Button, Card, Modal, Input, Navbar

# Or from presets for specialized widgets
from faststrap.presets import LoadingButton, KPICard, MetricCard

# 2. Render in FastHTML
@app.get("/")
def home():
    return Card(
        Button("Get Started", variant="primary", pill=True),
        title="Welcome to FastStrap",
    )
```

---

## 📖 Embedding Previews in MkDocs Documentation

To embed an interactive component preview in any markdown documentation page:

```html
<iframe
  src="http://localhost:8080/embed/Button?variant=primary&size=lg&pill=true&text=Click+Me"
  width="100%"
  height="200"
  frameborder="0"
  data-faststrap-preview
></iframe>
```

When deployed to production, replace `localhost:8080` with your hosted studio base URL (`STUDIO_BASE_URL` env variable).

Add the bridge script to your documentation site (`extra_javascript` in `mkdocs.yml`) for automatic iframe height adjustments and theme synchronization:

```html
<script src="/studio-static/js/embed.js"></script>
```

---

## 🧪 Running Tests

```bash
# Run full automated test suite (85 tests)
pytest tests/ -q

# Run code linter
ruff check faststrap_studio tests
```

---

## 📂 Architecture Overview

```
faststrap_studio/
├── __init__.py                 # Lazy package exports (app, cli)
├── main.py                     # Entry point, static files mounting & CORS
├── config.py                   # Environment & base settings
├── catalogue/                  # Modular component specifications & controls (86 components)
│   ├── __init__.py             # Unified CATALOGUE registry & metadata index
│   ├── actions.py              # Buttons, FABs, Toolbars, Segmented Controls
│   ├── display.py              # Cards, Tables, DataCards, Metrics, Tags, Stepper
│   ├── forms.py                # Inputs, Selects, Switches, DatePickers, Sliders, OTP
│   ├── feedback.py             # Alerts, Toasts, Modals, Loaders, Placeholders
│   ├── layout.py               # Containers, Grids, Separators, Page Headers
│   ├── navigation.py           # Navbars, Tabs, Breadcrumbs, Pagination, Dropdowns
│   └── patterns.py             # Pricing Tiers, Feature Highlights, Marketing
├── routes/
│   ├── meta.py                 # Gallery (/), Studio (/studio/{name}), API (/api/catalogue)
│   ├── preview.py              # Isolated iframe canvas with type-safe param parser (/preview/{name})
│   ├── embed.py                # Clean widget endpoint for documentation embeds (/embed/{name})
│   ├── demo.py                 # Interactive HTMX sandbox pages (/demo/*)
│   ├── mock.py                 # Realistic mock backend endpoints with latency simulation
│   ├── theme.py                # Cookie-persisted dark/light theme switcher
│   ├── sandbox.py              # Safe code editor & multi-device preview (/sandbox)
│   ├── export.py               # FastHTML app generator & download (/export/{name})
│   └── assets.py               # Optimized head asset injector
├── static/
│   ├── css/studio.css          # Studio stylesheet & design tokens
│   ├── js/studio.js           # Debounced sync, clipboard, resizer & lazy loader
│   └── js/embed.js            # Bridge script for MkDocs documentation sites
└── tests/
    └── test_catalogue_render.py# Automated pytest suite for all specs & endpoints
```

