wilco 0.1.2__tar.gz

wilco-0.1.2/.claude/settings.local.json

@@ -0,0 +1,58 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(pnpm install:*)",
+      "Bash(pnpm add:*)",
+      "Bash(uv sync:*)",
+      "Bash(uv run python:*)",
+      "Bash(ls:*)",
+      "Bash(pnpm typecheck:*)",
+      "Bash(curl:*)",
+      "Bash(pnpm dev)",
+      "Bash(pkill:*)",
+      "WebSearch",
+      "Bash(make start:*)",
+      "mcp__chrome-devtools__list_pages",
+      "mcp__chrome-devtools__navigate_page",
+      "mcp__chrome-devtools__take_snapshot",
+      "mcp__chrome-devtools__click",
+      "mcp__chrome-devtools__list_console_messages",
+      "mcp__chrome-devtools__get_console_message",
+      "mcp__chrome-devtools__list_network_requests",
+      "mcp__chrome-devtools__get_network_request",
+      "mcp__chrome-devtools__evaluate_script",
+      "mcp__chrome-devtools__take_screenshot",
+      "WebFetch(domain:pypi.org)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.npmjs.com)",
+      "WebFetch(domain:esbuild.github.io)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(uv run pytest:*)",
+      "Bash(tree:*)",
+      "Bash(find:*)",
+      "Bash(mkdir:*)",
+      "Bash(python3:*)",
+      "mcp__chrome-devtools__wait_for",
+      "mcp__chrome-devtools__resize_page",
+      "Bash(make test:*)",
+      "Bash(make wheel:*)",
+      "Bash(uv init:*)",
+      "Bash(uv run:*)",
+      "WebFetch(domain:unfoldadmin.com)",
+      "mcp__chrome-devtools__new_page",
+      "mcp__chrome-devtools__fill_form",
+      "Bash(pnpm test:run:*)",
+      "Bash(pnpm build:loader:*)",
+      "mcp__chrome-devtools__fill",
+      "Bash(make format:*)",
+      "Bash(make format-frontend:*)",
+      "Bash(make test-frontend:*)",
+      "mcp__chrome-devtools__upload_file",
+      "Bash(cat:*)",
+      "Bash(uv build:*)",
+      "Bash(unzip:*)",
+      "Bash(uv lock:*)",
+      "Bash(uv pip install:*)"
+    ]
+  }
+}

wilco-0.1.2/.gitignore

@@ -0,0 +1,5 @@
+**/.DS_Store
+**/__pycache__/*.pyc
+/.idea/
+node_modules/
+/dist/

wilco-0.1.2/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Django Admin Live Preview**: New `LivePreviewAdminMixin` enables real-time component preview in Django admin forms. The preview updates automatically when form fields lose focus, showing validation errors or the updated component.
+- **Standalone Loader**: Self-contained JavaScript loader (`loader.js`) for rendering wilco components in server-rendered pages without a full React app. Includes React, transforms ESM bundles at runtime, and manages component lifecycle.
+- **Live Loader Extension**: Additional `live-loader.js` script that adds live preview functionality to the standalone loader, with debounced validation and error display.
+- **Django Template Tags**: `{% wilco_component %}` and `{% wilco_loader_script %}` template tags for embedding components in Django templates.
+- **Component Widget**: `WilcoComponentWidget` class for rendering components in Django admin readonly fields.
+- **Multi-source Registry**: `ComponentRegistry.add_source()` now supports multiple component directories with optional prefixes.
+- **Django App Autodiscovery**: Automatically discovers components from `components/` directories in Django apps, prefixed with the app label (e.g., `store:product`).
+- **Bundle Caching**: Django bridge caches bundles in memory with file mtime invalidation.
+- **Product Component Modes**: Example product component now supports `list` and `detail` display modes.
+- **Product List Component**: New `product_list` component for displaying grids of products.
+- **Product Preview Component**: New `product_preview` component showing both list and detail modes for admin preview.
+- **Goober CSS-in-JS**: Integrated goober (~1KB) for styled-components-like styling with design tokens.
+- **useComponent Hook**: Standalone loader now supports `useComponent()` for dynamic component loading with React Suspense.
+- **Client-side Image Preview**: Live preview supports blob URLs for previewing uploaded images before form submission.
+
+### Changed
+
+- **Barrel Pattern**: Example components now use barrel pattern with separate implementation and style files.
+- **Component Composition**: ProductList and ProductPreview now use `useComponent("store:product")` instead of inline implementations.
+
+- **Bundle Hash**: Metadata endpoint now includes content hash for cache busting.
+- **Cache Headers**: Bundle responses use `immutable` cache directive for better CDN support.
+- **Product Model**: Example Django project now uses `ImageField` instead of URL field for product images.
+
+### Documentation
+
+- Added FastAPI integration guide (`docs/fastapi.rst`)
+- Added Django integration guide (`docs/django.rst`)
+- Added standalone loader internals documentation (`docs/internals/standalone.rst`)
+- Added JavaScript architecture overview (`docs/javascripts.rst`)

wilco-0.1.2/CLAUDE.md

@@ -0,0 +1,146 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**wilco** is a proof-of-concept framework that enables Python backends to serve isolated React/TypeScript components to a Vite-based frontend. Components are defined in the Python codebase alongside their TypeScript implementations, then dynamically bundled with esbuild and loaded by the frontend at runtime.
+
+## Architecture
+
+```
+wilco/
+├── pyproject.toml              # Python package config
+├── uv.lock
+├── src/
+│   ├── wilco/                  # Python package
+│   │   ├── __init__.py
+│   │   ├── __main__.py         # Development server entry point
+│   │   ├── registry.py         # Component discovery
+│   │   ├── bundler.py          # esbuild integration
+│   │   ├── bridges/
+│   │   │   ├── __init__.py
+│   │   │   └── fastapi.py      # Mountable FastAPI router
+│   │   └── examples/           # Example components
+│   └── wilcojs/                # JavaScript/TypeScript packages
+│       └── react/              # React frontend app
+│           ├── package.json
+│           ├── index.html
+│           ├── src/
+│           │   ├── App.tsx
+│           │   ├── api/
+│           │   │   └── bundles.ts
+│           │   └── loader/
+│           │       ├── ServerComponent.tsx
+│           │       ├── useComponent.ts
+│           │       └── wilco.ts
+│           ├── tsconfig.json
+│           └── vite.config.ts
+├── tests/                      # Python tests
+└── docs/
+```
+
+### Key Concepts
+
+- **Co-located components**: Each component has a Python package with `__init__.py`, `index.tsx` (React implementation), and optional `schema.json` (metadata/props)
+- **Dynamic bundling**: Backend uses esbuild (from frontend's node_modules) to bundle TypeScript components on-demand
+- **Runtime loading**: Frontend transforms ESM imports to use `window.__MODULES__`, then executes bundled code via `new Function()`
+- **Bridge pattern**: The `wilco.bridges.fastapi` module provides a mountable router factory for easy integration
+
+### API Endpoints
+
+- `GET /api/bundles` - List available bundles (names only)
+- `GET /api/bundles/{name}.js` - Get bundled JavaScript for a component
+- `GET /api/bundles/{name}/metadata` - Get component metadata (title, description, props)
+
+## Commands
+
+### Backend (Python/uv)
+
+```bash
+# Install dependencies
+uv sync
+
+# Run development server (port 8000)
+uv run python -m wilco
+
+# Run tests
+uv run pytest
+uv run pytest tests/test_file.py -k "test_name"
+```
+
+### Frontend (Vite/pnpm)
+
+```bash
+cd src/wilcojs/react
+
+# Install dependencies
+pnpm install
+
+# Run development server (port 5173, proxies /api to backend)
+pnpm dev
+
+# Type checking
+pnpm typecheck
+
+# Build for production
+pnpm build
+```
+
+### Running the POC
+
+**Option 1: Using Procfile (recommended)**
+```bash
+# Install a process manager (honcho, foreman, or overmind)
+pip install honcho  # or: brew install overmind
+
+# Start both services
+honcho start        # or: overmind start
+```
+
+**Option 2: Manual**
+```bash
+# Terminal 1
+uv run python -m wilco
+
+# Terminal 2
+cd src/wilcojs/react && pnpm dev
+```
+
+Open http://localhost:5173
+
+### Hot Reloading
+
+- **Backend**: uvicorn runs with `reload=True`, auto-reloads on Python file changes
+- **Frontend**: Vite provides HMR (Hot Module Replacement) for instant updates
+
+## Adding New Components
+
+1. Create a component package: `src/wilco/examples/<name>/` (or your own components directory)
+2. Add `__init__.py` (can be empty)
+3. Add `index.tsx` with a default export React component
+4. Optionally add `schema.json` with title, description, and props schema
+5. Component will be auto-discovered and available at `/api/bundles/<name>.js`
+
+## Using the Bridge Pattern
+
+The `wilco.bridges.fastapi` module provides a `create_router()` factory for integrating with any FastAPI app:
+
+```python
+from fastapi import FastAPI
+from wilco import ComponentRegistry
+from wilco.bridges.fastapi import create_router
+
+app = FastAPI()
+registry = ComponentRegistry(Path("./my_components"))
+app.include_router(create_router(registry), prefix="/api")
+```
+
+## Frontend State Management
+
+Uses `@tanstack/react-query` for server state:
+- `useBundles()` - Fetch list of available bundles
+- `useBundleMetadata(name)` - Fetch metadata for a specific bundle
+- `useBundleCode(name)` - Fetch bundled JavaScript code
+
+Hooks are defined in `src/wilcojs/react/src/api/bundles.ts`.

wilco-0.1.2/Makefile

@@ -0,0 +1,55 @@
+.PHONY: start test test-backend test-frontend install clean wheel format format-python format-frontend build-loader publish publish-test
+
+# Start development servers (default target)
+start:
+	overmind start
+
+# Build the standalone loader (compiles TypeScript to JavaScript)
+build-loader:
+	cd src/wilcojs/react && pnpm build:loader
+
+# Build Python wheel (includes pre-built JavaScript assets)
+wheel: build-loader
+	uv build
+
+# Publish to PyPI
+publish: wheel
+	uv run twine upload dist/*
+
+# Publish to TestPyPI (for testing before production release)
+publish-test: wheel
+	uv run twine upload --repository testpypi dist/*
+
+# Run all tests
+test: test-backend test-frontend
+
+# Run backend tests (Python/pytest)
+test-backend:
+	uv run pytest
+
+# Run frontend tests (TypeScript typecheck + Vitest)
+test-frontend:
+	cd src/wilcojs/react && pnpm typecheck && pnpm test:run
+
+# Install all dependencies
+install:
+	uv sync
+	cd src/wilcojs/react && pnpm install
+
+# Clean build artifacts
+clean:
+	rm -rf .pytest_cache
+	rm -rf dist
+	rm -rf src/wilcojs/react/dist
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+
+# Format all code
+format: format-python format-frontend
+
+# Format Python files with ruff (4 spaces, 120 chars)
+format-python:
+	uv run ruff format src tests
+
+# Format frontend files with biome
+format-frontend:
+	cd src/wilcojs/react && pnpm exec biome format --write .

wilco-0.1.2/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: wilco
+Version: 0.1.2
+Summary: Serve React components from Python backends
+Project-URL: Homepage, https://github.com/user/wilco
+Project-URL: Documentation, https://github.com/user/wilco#readme
+Project-URL: Repository, https://github.com/user/wilco
+Project-URL: Issues, https://github.com/user/wilco/issues
+License-Expression: MIT
+Keywords: components,django,esbuild,fastapi,react,typescript
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: django>=4.2.0; extra == 'dev'
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-benchmark>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.8.0; extra == 'dev'
+Requires-Dist: twine>=6.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# wilco
+
+**Server-defined React components for Python backends.**
+
+Wilco lets you define React components alongside your Python code and serve them dynamically to any frontend. Components are bundled on-demand with esbuild and loaded at runtime—no build step required for your component library.
+
+## Why wilco?
+
+- **Co-locate components with backend logic**: Keep your UI components next to the Python code that powers them
+- **No frontend build pipeline**: Components are bundled on-the-fly when requested
+- **Full source map support**: Debug your TypeScript directly in browser devtools
+- **Component composition**: Components can dynamically load other components
+- **Framework agnostic**: Mount the API router in any FastAPI (or compatible) app
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install wilco
+```
+
+### Create a component
+
+```
+my_components/
+└── greeting/
+    ├── __init__.py
+    ├── index.tsx
+    └── schema.json
+```
+
+```tsx
+// index.tsx
+interface GreetingProps {
+  name: string;
+  formal?: boolean;
+}
+
+export default function Greeting({ name, formal = false }: GreetingProps) {
+  const message = formal ? `Good day, ${name}.` : `Hey ${name}!`;
+  return <p>{message}</p>;
+}
+```
+
+```json
+{
+  "title": "Greeting",
+  "description": "A friendly greeting component",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "formal": { "type": "boolean", "default": false }
+  },
+  "required": ["name"]
+}
+```
+
+### Mount the API
+
+```python
+from pathlib import Path
+from fastapi import FastAPI
+from wilco import ComponentRegistry
+from wilco.bridges.fastapi import create_router
+
+app = FastAPI()
+registry = ComponentRegistry(Path("./my_components"))
+app.include_router(create_router(registry), prefix="/api")
+```
+
+### Load components in React
+
+```tsx
+import { useComponent } from '@wilcojs/react';
+
+function App() {
+  const Greeting = useComponent('greeting');
+  return <Greeting name="World" />;
+}
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/bundles` | List available components |
+| `GET /api/bundles/{name}.js` | Get bundled JavaScript |
+| `GET /api/bundles/{name}/metadata` | Get component metadata |
+
+## Component Structure
+
+Each component is a Python package with:
+
+| File | Required | Description |
+|------|----------|-------------|
+| `__init__.py` | Yes | Package marker |
+| `index.tsx` | Yes | React component (default export) |
+| `schema.json` | No | Props schema and metadata |
+
+Components can include additional `.tsx` files—they're all bundled together.
+
+## Component Composition
+
+Components can load other components dynamically:
+
+```tsx
+import { useComponent } from '@wilcojs/react';
+
+export default function Dashboard() {
+  const Chart = useComponent('chart');
+  const Table = useComponent('table');
+
+  return (
+    <div>
+      <Chart data={...} />
+      <Table rows={...} />
+    </div>
+  );
+}
+```
+
+## Development Server
+
+Run the built-in development server to preview components:
+
+```bash
+uv run python -m wilco
+```
+
+Then start the frontend:
+
+```bash
+cd src/wilcojs/react && pnpm dev
+```
+
+Open http://localhost:5173 to browse and test your components.
+
+## Requirements
+
+- Python 3.10+
+- Node.js (for esbuild bundling)
+- React 18+ on the frontend
+
+## About the Name
+
+Named after **Roger Wilco**, the janitor-turned-hero from Sierra's *Space Quest* series. Roger stumbles into saving the galaxy while just trying to do his job. Like its namesake, this framework gets the job done despite the chaos—bridging Python backends with React frontends through dynamic bundling magic.
+
+## License
+
+MIT

wilco-0.1.2/Procfile

@@ -0,0 +1,2 @@
+backend: uv run python -m wilco
+frontend: cd src/wilcojs/react && pnpm dev

wilco-0.1.2/README.md

@@ -0,0 +1,151 @@
+# wilco
+
+**Server-defined React components for Python backends.**
+
+Wilco lets you define React components alongside your Python code and serve them dynamically to any frontend. Components are bundled on-demand with esbuild and loaded at runtime—no build step required for your component library.
+
+## Why wilco?
+
+- **Co-locate components with backend logic**: Keep your UI components next to the Python code that powers them
+- **No frontend build pipeline**: Components are bundled on-the-fly when requested
+- **Full source map support**: Debug your TypeScript directly in browser devtools
+- **Component composition**: Components can dynamically load other components
+- **Framework agnostic**: Mount the API router in any FastAPI (or compatible) app
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install wilco
+```
+
+### Create a component
+
+```
+my_components/
+└── greeting/
+    ├── __init__.py
+    ├── index.tsx
+    └── schema.json
+```
+
+```tsx
+// index.tsx
+interface GreetingProps {
+  name: string;
+  formal?: boolean;
+}
+
+export default function Greeting({ name, formal = false }: GreetingProps) {
+  const message = formal ? `Good day, ${name}.` : `Hey ${name}!`;
+  return <p>{message}</p>;
+}
+```
+
+```json
+{
+  "title": "Greeting",
+  "description": "A friendly greeting component",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "formal": { "type": "boolean", "default": false }
+  },
+  "required": ["name"]
+}
+```
+
+### Mount the API
+
+```python
+from pathlib import Path
+from fastapi import FastAPI
+from wilco import ComponentRegistry
+from wilco.bridges.fastapi import create_router
+
+app = FastAPI()
+registry = ComponentRegistry(Path("./my_components"))
+app.include_router(create_router(registry), prefix="/api")
+```
+
+### Load components in React
+
+```tsx
+import { useComponent } from '@wilcojs/react';
+
+function App() {
+  const Greeting = useComponent('greeting');
+  return <Greeting name="World" />;
+}
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/bundles` | List available components |
+| `GET /api/bundles/{name}.js` | Get bundled JavaScript |
+| `GET /api/bundles/{name}/metadata` | Get component metadata |
+
+## Component Structure
+
+Each component is a Python package with:
+
+| File | Required | Description |
+|------|----------|-------------|
+| `__init__.py` | Yes | Package marker |
+| `index.tsx` | Yes | React component (default export) |
+| `schema.json` | No | Props schema and metadata |
+
+Components can include additional `.tsx` files—they're all bundled together.
+
+## Component Composition
+
+Components can load other components dynamically:
+
+```tsx
+import { useComponent } from '@wilcojs/react';
+
+export default function Dashboard() {
+  const Chart = useComponent('chart');
+  const Table = useComponent('table');
+
+  return (
+    <div>
+      <Chart data={...} />
+      <Table rows={...} />
+    </div>
+  );
+}
+```
+
+## Development Server
+
+Run the built-in development server to preview components:
+
+```bash
+uv run python -m wilco
+```
+
+Then start the frontend:
+
+```bash
+cd src/wilcojs/react && pnpm dev
+```
+
+Open http://localhost:5173 to browse and test your components.
+
+## Requirements
+
+- Python 3.10+
+- Node.js (for esbuild bundling)
+- React 18+ on the frontend
+
+## About the Name
+
+Named after **Roger Wilco**, the janitor-turned-hero from Sierra's *Space Quest* series. Roger stumbles into saving the galaxy while just trying to do his job. Like its namesake, this framework gets the job done despite the chaos—bridging Python backends with React frontends through dynamic bundling magic.
+
+## License
+
+MIT