Metadata-Version: 2.4
Name: faststrap-preview-studio
Version: 0.9.1
Summary: Interactive Component Studio & Live Documentation Preview Engine for FastStrap + FastHTML
Author: FastStrap Team
License: MIT
Project-URL: Homepage, https://github.com/Faststrap-org/FastStrap_Studio
Project-URL: Repository, https://github.com/Faststrap-org/FastStrap_Studio
Project-URL: Issues, https://github.com/Faststrap-org/FastStrap_Studio/issues
Project-URL: Changelog, https://github.com/Faststrap-org/FastStrap_Studio/blob/main/CHANGELOG.md
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

[![PyPI version](https://img.shields.io/pypi/v/faststrap-preview-studio)](https://pypi.org/project/faststrap-preview-studio/)
[![Python versions](https://img.shields.io/pypi/pyversions/faststrap-preview-studio)](https://pypi.org/project/faststrap-preview-studio/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

An interactive, local-first component explorer and code playground for [FastStrap](https://github.com/Faststrap-org/Faststrap) and [FastHTML](https://fastht.ml/). Browse component examples, inspect their parameters, adjust previews, and copy Python snippets into your own projects.

The Studio runs on your computer; it is not a hosted app builder or a public code-execution service. Its core assets and browser runtimes are included locally. A few optional integrations (such as KaTeX, Mermaid, Chart.js, Plotly, and GSAP) load their renderer assets from CDNs and therefore need an internet connection when used.

## Preview

Images use version-pinned GitHub URLs so they render in PyPI's project description as well as on GitHub.

<p align="center">
  <img src="https://raw.githubusercontent.com/Faststrap-org/FastStrap_Studio/v0.9.0/screenshots/faststrap_studio_dark.png" alt="FastStrap Preview Studio component gallery in dark mode" width="100%" />
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/Faststrap-org/FastStrap_Studio/v0.9.0/screenshots/faststrap_studio_ligh1.png" alt="FastStrap Preview Studio component gallery in light mode" width="49%" />
  <img src="https://raw.githubusercontent.com/Faststrap-org/FastStrap_Studio/v0.9.0/screenshots/faststrap_studio_btn_light.png" alt="FastStrap Preview Studio component controls and code view" width="49%" />
</p>

## Install And Run

Requires Python 3.10 or newer.

```bash
python -m pip install faststrap-preview-studio
faststrap-preview
```

Then open <http://127.0.0.1:8080>. The server binds to loopback by default, so it is available on your computer only.

To use another port or host, set `PORT` or `HOST` before starting the command. For example, in PowerShell:

```powershell
$env:PORT = "8090"
faststrap-preview
```

## What You Can Do

- Browse **86 curated component previews**, organized by category, with import guidance and example code.
- Adjust supported component parameters and inspect the result in an isolated preview canvas.
- Compare mobile (375px), tablet (768px), laptop (1024px), and full-width desktop layouts.
- Switch canvas backgrounds and use the light/dark theme controls.
- Explore interactive HTMX demos for patterns such as search, loading actions, validation, and tables.
- Copy FastHTML/FastStrap snippets into an application.
- Embed curated component previews in documentation using the Studio's `/embed/{component}` route.
- Use the local sandbox to run complete examples on your own machine.

## Local Playground And Safety

The sandbox is designed for a developer running the Studio locally and executing code they trust. In its default local mode, submitted Python can run with normal Python capabilities. **Do not expose the sandbox to untrusted users or the public internet.** This is a local learning tool, not an isolation boundary.

The default host is `127.0.0.1`. Setting `HOST=0.0.0.0` makes the server reachable from other machines on the network and should be done only when you understand that exposure.

For a hosted documentation integration that needs curated previews but not arbitrary code execution, set:

```text
STUDIO_ENABLE_SANDBOX=false
```

This removes the `/sandbox/*` code-runner routes. Setting `STUDIO_ENABLE_ARBITRARY_EXEC=false` applies AST restrictions to sandbox execution, but it is not process or container isolation and should not be treated as safe public multi-user execution. Keep hosted deployments appropriately isolated and expose only the routes they need.

Optional integration examples may fetch renderer scripts or styles from third-party CDNs. The core Studio shell, Bootstrap/FastStrap styles, and FastHTML browser runtimes are served from the installed package.

## Embedding A Preview

When the Studio is reachable from your documentation site, an iframe can display a component preview. Replace the example host with the Studio's actual base URL:

```html
<iframe
  src="https://studio.example.com/embed/Button?variant=primary&text=Try+FastStrap"
  width="100%"
  height="280"
  title="FastStrap Button preview"
  data-faststrap-preview
></iframe>
```

The Studio's `/studio/{component}` page can generate embed markup using `STUDIO_BASE_URL`. The optional bridge script at `/studio-static/js/embed.js` synchronizes theme changes and adjusts iframe height. For a public documentation deployment, disable the arbitrary-code sandbox and review which routes and network access are exposed before hosting it.

## Install From Source

```bash
git clone https://github.com/Faststrap-org/FastStrap_Studio.git
cd FastStrap_Studio
python -m venv .venv
```

Activate the environment, then install the project and development tools:

```powershell
# Windows PowerShell
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python main.py
```

```bash
# macOS/Linux
source .venv/bin/activate
python -m pip install -e ".[dev]"
python main.py
```

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `HOST` | `127.0.0.1` | Server bind address. Use the loopback default for local use. |
| `PORT` | `8080` | Server port. |
| `RELOAD` | `false` | Enable Uvicorn reload mode for development. |
| `STUDIO_BASE_URL` | `http://localhost:8080` | Base URL used to generate absolute preview/embed URLs. |
| `STUDIO_ENABLE_SANDBOX` | `true` | Set to `false` to omit `/sandbox/*` routes. |
| `STUDIO_ENABLE_ARBITRARY_EXEC` | `true` | Allows trusted local examples to use normal Python execution; not a security boundary. |

## Development

Run the automated tests and linter from the repository root:

```bash
python -m pytest -q
ruff check faststrap_studio tests
```

The package is organized into the `faststrap_studio` Python package, component catalogue, route modules, local static assets, and a repository-level `tests/` suite. Frontend runtimes vendored in `faststrap_studio/static/vendor/` include their version and license notices in that directory.

## Links

- [FastStrap Preview Studio on PyPI](https://pypi.org/project/faststrap-preview-studio/)
- [Source repository](https://github.com/Faststrap-org/FastStrap_Studio)
- [Issue tracker](https://github.com/Faststrap-org/FastStrap_Studio/issues)
- [FastStrap documentation](https://faststrap-org.github.io/Faststrap/)
- [Changelog](CHANGELOG.md)
- [License](LICENSE)
