prefab-ui 0.1.0__tar.gz

prefab_ui-0.1.0/.claude/skills/docs-build-pipeline/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: docs-build-pipeline
+description: >
+  How the Prefab docs build pipeline works: the scripts in
+  docs/_preview-build/, what they do, and how to update them. Use when
+  modifying build scripts, debugging doc generation failures, adding new
+  doc source paths, updating CSS safelists, or troubleshooting preview
+  rendering.
+---
+
+## Overview
+
+`prefab dev build-docs` runs the full pipeline. The scripts live in
+`docs/_preview-build/` and execute in this order:
+
+1. **build:embed** (`npm run build:embed` in `renderer/`) — builds
+   `renderer/src/embed.tsx` as a self-contained IIFE via Vite library mode.
+   Output: `docs/embed.js`. Mintlify auto-injects `.js` files from the docs
+   directory as `<script>` tags on every page, so the IIFE executes and
+   registers `window.__prefab = { mountPreview }`. The build inlines all
+   dependencies (React, Radix, Recharts, Tailwind CSS) into a single file.
+   Config: `renderer/vite.config.embed.ts`.
+2. **render_previews.py** — finds `<ComponentPreview auto>` blocks in MDX
+   files, executes the Python code, serializes component trees to JSON,
+   rebuilds the CodeGroup interior (Python + JSON tabs) and the `json`
+   prop on the tag
+3. **generate_content.py** — concatenates all rendered MDX into
+   `content.html` for Tailwind to scan
+4. **Tailwind CSS build** — compiles `input.css` → scoped CSS using the
+   content.html and MDX files as sources
+5. **scope_css.py** — rewrites the compiled CSS to scope under shadow DOM
+   (`:host` selectors)
+6. **generate_playground_bundle.py** — builds the playground JSON bundle
+7. **extract_examples.py** — extracts Python code blocks from MDX files
+   into `renderer/src/playground/examples.json`
+8. **generate_protocol_pages.py** — introspects Pydantic models and writes
+   one MDX page per component/action into `docs/protocol/`
+9. **generate_protocol_ref.py** — updates `## Protocol Reference` sections
+   in component MDX files with compact pseudocode JSON blocks from Pydantic schemas
+
+## Source Paths
+
+Scripts read MDX files from `docs/` (components, actions, patterns, etc.)
+and write generated output to:
+- `docs/embed.js` — self-contained renderer module (built from `renderer/src/embed.tsx`)
+- `docs/protocol/` — autogenerated protocol reference pages
+- `docs/_preview-build/content.html` — concatenated content for Tailwind
+- `renderer/src/playground/examples.json` — playground examples
+- `renderer/src/playground/bundle.json` — playground bundle
+
+If the docs directory structure changes, update the path constants in each
+script. Key locations:
+- `render_previews.py`: `docs_dir = Path(__file__).resolve().parents[1]`
+- `generate_protocol_pages.py`: `PROTOCOL_DIR = Path(__file__).resolve().parents[1] / "protocol"`
+- `extract_examples.py`: `docs_dir = root / "docs"`
+- `input.css`: `@source "../**/*.mdx"` glob
+
+## CSS Safelist
+
+`renderer/src/index.css` has `@source inline(...)` lines that safelist
+Tailwind classes available via `cssClass`. When adding new layout utilities
+or CSS class patterns to components, extend the appropriate safelist line.
+
+Current safelists cover: gap, grid-cols, items-*, justify-*, place-items-*,
+flex utilities, spacing, sizing, typography, colors, and more.
+
+## Common Tasks
+
+**Adding a new component:** After writing the Python model and renderer,
+run `prefab dev build-docs` to generate the protocol page in `docs/protocol/`.
+Then write the component doc in `docs/components/`.
+
+**Changing doc directory structure:** Update path constants in all scripts
+listed under Source Paths above, plus the `@source` glob in `input.css`.
+
+**Debugging blank previews:** Usually means the Python code block in
+`<ComponentPreview auto>` raised an error during `render_previews.py`.
+Run the script directly to see the traceback:
+```bash
+uv run docs/_preview-build/render_previews.py
+```
+
+**Previews render but look wrong in browser:** Check whether the needed
+Tailwind classes are safelisted in `renderer/src/index.css`. Dynamic
+classes passed via `cssClass` must appear in a safelist to be included
+in the compiled CSS.
+
+## Embed Module Architecture
+
+`docs/embed.js` is a self-contained IIFE built from
+`renderer/src/embed.tsx` via Vite library mode
+(`renderer/vite.config.embed.ts`). It registers
+`window.__prefab = { mountPreview }` when executed.
+
+Mintlify auto-injects any `.js` file in the docs directory as a `<script>`
+tag on every page. This means the IIFE runs before React components mount,
+so `window.__prefab.mountPreview` is available synchronously when
+`ComponentPreview` needs it. Mintlify does NOT serve `.js` files as
+fetchable static assets (dynamic `import()` fails), which is why the IIFE
++ auto-injection approach is used instead of ES module format.
+
+All dependencies (React, Radix, Recharts, Tailwind CSS) are bundled
+inline — no external imports. The CSS is inlined as a string via Vite's
+`?inline` import and processed through the `tailwindShadowDom` plugin
+(shared in `renderer/vite-plugins.ts`) to strip `@property` declarations
+that don't work in shadow DOM.
+
+The same library-mode build mechanism could serve air-gapped MCP app
+distribution: ship the built bundle alongside an MCP server so the client
+can render Prefab UI without a live server or CDN.

prefab_ui-0.1.0/.claude/skills/writing-component-docs/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: writing-component-docs
+description: >
+  Conventions for authoring and maintaining Prefab component and action
+  documentation pages (docs/components/*.mdx, docs/actions/*.mdx). Use when
+  creating new component docs, updating existing docs after API changes,
+  adding examples, or editing Protocol/API Reference sections.
+---
+
+## Page Structure
+
+Every component doc follows this section order (h2 headers for TOC):
+
+1. **Frontmatter** — `title`, `description`, `icon`
+2. **Intro paragraph** — one sentence explaining what the component does
+3. **## Basic Usage** — simplest working example, no extra options
+4. **## [Feature sections]** — one h2 per notable feature/variant
+5. **## API Reference** — Python parameters (Card/ParamField format)
+6. **## Protocol Reference** — protocol link + inline JSON schema
+
+The page title doesn't appear in the TOC, so "Basic Usage" is the user's
+entry point. Never drop straight into a preview without a heading.
+
+## Component Previews
+
+Only edit the Python code block inside `<ComponentPreview auto>`. The JSON
+prop, CodeGroup wrapper, and Protocol tab are all generated — never write
+them by hand.
+
+After editing previews, run `prefab dev build-docs` to regenerate.
+
+**Code block titles:** Always give the Python block a title (e.g.,
+`` ```python Python ``). A block without a title produces a zero-width tab in
+the CodeGroup that users can't click. The title goes before other directives:
+`` ```python Python {5} ``.
+
+**Python code style inside previews:**
+- Target ~80 character line width
+- Use implicit string concatenation for long text
+- Wrap function arguments when they don't fit on one line
+- Include all necessary imports
+
+## API Reference
+
+Use Card + ParamField. Lead with the most important parameters:
+
+```mdx
+<Card icon="code" title="ComponentName Parameters">
+<ParamField body="param_name" type="str" default="value">
+  Description of the parameter.
+</ParamField>
+</Card>
+```
+
+## Protocol Reference
+
+This section is **auto-generated** by `generate_protocol_ref.py` (run via
+`prefab dev build-docs`). Do not edit it by hand — it will be overwritten.
+
+The generator reads `<Card icon="code" title="X Parameters">` cards from
+the API Reference section, introspects the corresponding Pydantic model,
+and produces compact pseudocode JSON blocks with links to the full protocol
+pages. Components whose Card titles don't end in "Parameters" (like
+If/Elif/Else) are skipped, allowing hand-written Protocol Reference
+sections for special cases.
+
+Inline JSON schema conventions (for reference / hand-written exceptions):
+- Append `?` to optional property names
+- Show default values inline for bools and enums
+- Use `(required)` after the type for required props
+- Use `[Component]` for children arrays
+- Protocol slug is kebab-case of wire type (e.g., `AreaChart` → `area-chart`)
+
+## Content Rules
+
+- Use Hitchhiker's Guide to the Galaxy references for placeholder content.
+  Never use "Lorem ipsum" or marketing copy about the component itself.
+- Do NOT add per-field "Supports interpolation" callouts. Interpolation is
+  universal and documented centrally at `/patterns/interpolation`.
+
+## Files to Keep Aligned
+
+When the Python API or wire protocol changes, update all of these:
+
+- `src/prefab_ui/components/<name>.py` — Python model (source of truth)
+- `renderer/src/schemas/<name>.ts` — Zod schema
+- `renderer/src/components/` — renderer
+- `docs/components/<name>.mdx` — documentation
+- `schemas/fixtures/components/<Name>.json` — test fixtures
+- `skills/generative-prefab-ui/` — distributable skill for wire protocol generation
+- `skills/writing-prefab-python/` — distributable skill for Python DSL usage
+
+After any change: `prefab dev build-docs` then `uv run pytest tests/ -x`.

prefab_ui-0.1.0/.github/actions/run-pytest/action.yml

@@ -0,0 +1,18 @@
+name: "Run Pytest"
+description: "Run pytest with appropriate flags for the platform"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Run pytest
+      shell: bash
+      run: |
+        TIMEOUT="5"
+        MAX_PROCS="4"
+
+        PARALLEL_FLAGS="--numprocesses auto --maxprocesses $MAX_PROCS --dist worksteal"
+
+        uv run --no-sync pytest \
+          --timeout=$TIMEOUT \
+          $PARALLEL_FLAGS \
+          tests

prefab_ui-0.1.0/.github/actions/setup-uv/action.yml

@@ -0,0 +1,33 @@
+name: "Setup UV Environment"
+description: "Install uv and dependencies (requires checkout first)"
+
+inputs:
+  python-version:
+    description: "Python version to use"
+    required: false
+    default: "3.10"
+  resolution:
+    description: "Dependency resolution: locked, upgrade, or lowest-direct"
+    required: false
+    default: "locked"
+
+runs:
+  using: "composite"
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v7
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install dependencies
+      shell: bash
+      run: |
+        if [ "${{ inputs.resolution }}" == "locked" ]; then
+          uv sync --locked
+        elif [ "${{ inputs.resolution }}" == "upgrade" ]; then
+          uv sync --upgrade
+        else
+          uv sync --resolution ${{ inputs.resolution }}
+        fi

prefab_ui-0.1.0/.github/workflows/build-renderer.yml

@@ -0,0 +1,44 @@
+name: Build renderer
+
+on:
+  pull_request:
+    paths:
+      - "renderer/**"
+      - ".github/workflows/build-renderer.yml"
+
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: "Build docs/renderer.js for Mintlify"
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          ref: ${{ github.head_ref }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: renderer/package-lock.json
+
+      - run: npm ci
+        working-directory: renderer
+
+      - run: npm run build:renderer
+        working-directory: renderer
+
+      - run: cp renderer/dist/renderer.js docs/renderer.js
+
+      - name: Commit updated renderer.js
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add docs/renderer.js
+          git diff --cached --quiet && echo "No changes" || git commit -m "Rebuild docs/renderer.js" && git push

prefab_ui-0.1.0/.github/workflows/publish-renderer.yml

@@ -0,0 +1,52 @@
+# Publishes @prefecthq/prefab-ui to npm on release.
+#
+# Currently Mintlify loads renderer.js from the repo (committed by
+# build-renderer.yml on PR). Once we're cutting regular releases, we
+# should switch published docs to load from the npm CDN instead and
+# stop committing renderer.js to git. The CDN fallback in
+# component-preview.mdx already supports this — just remove
+# docs/renderer.js from the repo and gitignore it.
+name: Publish renderer to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    name: "Build & publish @prefecthq/prefab-ui"
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: "npm"
+          cache-dependency-path: renderer/package-lock.json
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Set npm version from git tag
+        working-directory: renderer
+        run: |
+          # Strip PEP 440 pre-release suffix: v0.1.0a1 → 0.1.0
+          RAW="${{ github.ref_name }}"
+          VERSION="${RAW#v}"
+          VERSION=$(echo "$VERSION" | sed -E 's/(a|b|rc)[0-9]+$//')
+          npm version "$VERSION" --no-git-tag-version
+
+      - run: npm ci
+        working-directory: renderer
+
+      - run: npm run build:publish
+        working-directory: renderer
+
+      - run: npm publish --access public --tag latest
+        working-directory: renderer

prefab_ui-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,27 @@
+name: Publish to PyPI
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: "Install uv"
+        uses: astral-sh/setup-uv@v7
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPi
+        run: uv publish -v dist/*

prefab_ui-0.1.0/.github/workflows/run-renderer-tests.yml

@@ -0,0 +1,40 @@
+name: Renderer Tests
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "renderer/**"
+      - ".github/workflows/run-renderer-tests.yml"
+
+  pull_request:
+    paths:
+      - "renderer/**"
+      - ".github/workflows/run-renderer-tests.yml"
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: "Renderer unit tests"
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    defaults:
+      run:
+        working-directory: renderer
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: renderer/package-lock.json
+
+      - run: npm ci
+      - run: npm test

prefab_ui-0.1.0/.github/workflows/run-static.yml

@@ -0,0 +1,42 @@
+name: Run static analysis
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  static_analysis:
+    timeout-minutes: 2
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: locked
+
+      - name: Install renderer dependencies
+        run: cd renderer && npm ci
+
+      - name: Run prek
+        uses: j178/prek-action@v1
+        env:
+          SKIP: no-commit-to-branch

prefab_ui-0.1.0/.github/workflows/run-tests.yml

@@ -0,0 +1,63 @@
+name: Tests
+
+env:
+  PY_COLORS: 1
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+
+  pull_request:
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  run_tests:
+    name: "Tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10"]
+        include:
+          - os: ubuntu-latest
+            python-version: "3.13"
+      fail-fast: false
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup uv
+        uses: ./.github/actions/setup-uv
+        with:
+          python-version: ${{ matrix.python-version }}
+          resolution: locked
+
+      - name: Run tests
+        uses: ./.github/actions/run-pytest
+
+  run_tests_lowest_direct:
+    name: "Tests with lowest-direct dependencies"
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Setup uv (lowest-direct)
+        uses: ./.github/actions/setup-uv
+        with:
+          resolution: lowest-direct
+
+      - name: Run tests
+        uses: ./.github/actions/run-pytest

prefab_ui-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+.ty/
+*.so
+
+# Node / renderer
+node_modules/
+renderer/dist/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Plans (internal strategy docs)
+plans/
+
+# Caches
+.loq_cache
+
+# Build artifacts (except renderer.js and playground-app.js — committed for Mintlify)
+docs/embed.js
+docs/css/preview.css
+docs/playground.js
+docs/component-bundle.js
+docs/_preview-build/content.html

prefab_ui-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,61 @@
+fail_fast: false
+
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v3.1.0
+    hooks:
+      - id: prettier
+        types_or: [yaml, json5, javascript, tsx, ts, css]
+        exclude: ^(renderer/src/ui/|docs/(embed|renderer)\.js)
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty check
+        entry: uv run --isolated ty check
+        language: system
+        types: [python]
+        files: ^src/|^tests/
+        pass_filenames: false
+        require_serial: true
+
+      - id: tsc
+        name: tsc (renderer type check)
+        entry: bash -c 'cd renderer && npx tsc --noEmit'
+        language: system
+        files: ^renderer/.*\.(ts|tsx)$
+        pass_filenames: false
+        require_serial: true
+
+      - id: loq
+        name: loq (file size limits)
+        entry: uv run loq
+        language: system
+        pass_filenames: false
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: no-commit-to-branch
+        name: prevent commits to main
+        args: [--branch, main]
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        exclude: ^(docs/(embed|renderer|playground-app)\.js|src/prefab_ui/renderer/app\.html)$
+        additional_dependencies:
+          - tomli

prefab_ui-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

prefab_ui-0.1.0/CLAUDE.md

@@ -0,0 +1,20 @@
+# Prefab
+
+## Git Hooks
+
+Pre-commit hooks are run via `prek`, not `pre-commit`. Run `prek` before committing.
+
+## Component Architecture
+
+**Pure-CSS kwargs resolve in Python, not the renderer.** When a Python component has a convenience kwarg that maps directly to CSS (like `spacing=4` → `my-4`), resolve it in `model_post_init` by compiling to `css_class` and marking the field `exclude=True`. The renderer should only see `cssClass` — it never needs to know about the kwarg. See `Row.gap`/`Row.align` and `Separator.spacing` for examples.
+
+## Component Documentation
+
+Doc conventions are encoded as agent skills in `.claude/skills/`:
+- `writing-component-docs` — page structure, preview format, API/Protocol reference conventions
+- `docs-build-pipeline` — how the build scripts work and when to update them
+
+After any changes, regenerate docs and schemas:
+```bash
+prefab dev build-docs
+```