React renderer with Claude Code

.github/workflows/build.yaml

@@ -24,21 +24,25 @@ jobs:
         with:
           python-version: "3.12"
           enable-cache: true
-          cache-dependency-glob: "requirements.txt"
+          cache-dependency-glob: "python/requirements.txt"
 
       - name: Install dependencies
+        working-directory: ./python
         run: |
           if [ -f requirements.txt ]; then uv pip install -r requirements.txt; fi
           uv pip install pytest
 
       - name: Install the package
+        working-directory: ./python
         run: |
           uv pip install .
 
       - name: Test with pytest
+        working-directory: ./python
         run: |
-          uv run pytest
+          PYTHONPATH=.. uv run pytest
 
       - name: Check if the main script is installed
+        working-directory: ./python
         run: |
           uv run convert_jsondoc --help

.github/workflows/publish.yaml

@@ -34,10 +34,12 @@ jobs:
         uses: astral-sh/setup-uv@v5
 
       - name: Install dependencies
+        working-directory: ./python
         run: |
           uv pip install --system toml
 
       - name: Extract version from tag and update pyproject.toml
+        working-directory: ./python
         run: |
           # Get the version from the tag (remove 'v' prefix)
           TAG_VERSION=${GITHUB_REF#refs/tags/v}
@@ -58,11 +60,13 @@ jobs:
           cat pyproject.toml | grep version
 
       - name: Build package
+        working-directory: ./python
         run: uv build --no-sources
 
       - name: Publish package to PyPI
         uses: pypa/[email protected]
         with:
+          packages-dir: python/dist/
           user: __token__
           password: ${{ secrets.PYPI_API_TOKEN }}
           verbose: true

.github/workflows/test.yaml

@@ -26,10 +26,12 @@ jobs:
       uses: astral-sh/setup-uv@v5
 
     - name: Install dependencies
+      working-directory: ./python
       run: uv sync --all-extras --dev
 
     - name: Run tests
+      working-directory: ./python
       run: |
-        uv run pytest
+        PYTHONPATH=.. uv run pytest
 
 

.gitignore

@@ -6,4 +6,5 @@ __pycache__
 build/
 *.docx
 *.pptx
-scratch/
+scratch/
+dist/

CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+JSON-DOC is a standardized format for storing structured content in JSON files, inspired by Notion's data model. It supports a wide variety of content types including paragraphs, headings, lists, tables, images, code blocks, and more.
+
+The project consists of:
+1. A JSON schema specification for the format
+2. A Python implementation
+3. A TypeScript implementation (in progress)
+4. Converters for various formats (HTML, Markdown, etc.)
+
+## Project Structure
+
+- `/schema/`: JSON schemas defining the structure of JSON-DOC files
+- `/python/`: Python implementation
+- `/ts/`: TypeScript implementation (in progress)
+- `/docs/`: Documentation
+- `/examples/`: Example files showing the format
+- `/tests/`: Tests for both implementations
+
+## Development Commands
+
+### Python Development
+
+```bash
+# Set up development environment
+cd /Users/onur/tc/JSON-DOC/python
+python -m pip install -e .
+python -m pip install -e ".[dev]"
+
+# Run tests
+cd /Users/onur/tc/JSON-DOC/python
+pytest
+
+# Run a specific test
+cd /Users/onur/tc/JSON-DOC/python
+pytest tests/test_serialization.py -v
+
+# Run validation tests
+cd /Users/onur/tc/JSON-DOC/python
+python tests/test_validation.py schema
+
+# Run linting
+cd /Users/onur/tc/JSON-DOC/python
+ruff check .
+ruff format .
+```
+
+### TypeScript Development
+
+```bash
+# Set up development environment
+cd /Users/onur/tc/JSON-DOC/ts
+npm install
+
+# Build TypeScript
+cd /Users/onur/tc/JSON-DOC/ts
+npm run build
+
+# Run tests
+cd /Users/onur/tc/JSON-DOC/ts
+npm test
+```
+
+## Architecture Overview
+
+### JSON-DOC Schema
+
+The JSON-DOC schema is defined in JSONSchema format, with the following primary components:
+
+1. **Page**: The top-level container for all content
+2. **Block**: Content blocks of various types (paragraph, heading, list item, etc.)
+3. **Rich Text**: Text content with formatting (bold, italic, etc.)
+4. **File**: External file references (images, etc.)
+
+Each block type has specific schemas and validation rules.
+
+### Python Implementation
+
+The Python implementation uses Pydantic models for validation and serialization, with:
+
+- Block types implemented as classes inheriting from a base Block class
+- Rich text types implemented as classes inheriting from a base RichText class
+- Serialization/deserialization functions for loading and saving JSON-DOC files
+- Converters for HTML, Markdown, and other formats
+
+Key modules:
+- `jsondoc.models`: Pydantic models for JSON-DOC
+- `jsondoc.serialize`: Functions for loading/saving JSON-DOC
+- `jsondoc.validate`: Schema validation
+- `jsondoc.convert`: Conversion between formats
+
+### TypeScript Implementation
+
+The TypeScript implementation is in progress, following similar architecture to the Python version:
+
+- Type definitions for all JSON-DOC structures
+- Functions for loading/saving JSON-DOC files
+- Schema validation
+- Converters for other formats
+
+## Testing Strategy
+
+- Schema validation tests ensure examples conform to schemas
+- Serialization tests ensure round-trip conversion preserves data
+- Conversion tests verify correct transformation between formats
+- Integration tests for end-to-end workflows
+
+## Implementation Notes
+
+1. The project follows a modular architecture with clear separation between:
+   - Schema definition
+   - Model implementation
+   - Validation
+   - Serialization
+   - Conversion
+
+2. The TypeScript implementation should follow the same patterns as the Python implementation, with appropriate adaptations for the TypeScript ecosystem.
+
+3. The core functionality is focused on:
+   - Loading JSON-DOC files into typed objects
+   - Validating JSON-DOC files against schemas
+   - Converting between JSON-DOC and other formats

docs/2025-05-21-json-doc-ts-prompt.md

@@ -0,0 +1,21 @@
+---
+title: "Implementing JSON-DOC TypeScript parser"
+author: "Onur <[email protected]>"
+date: "2025-05-21"
+---
+
+A lot of coding agent products went into production recently, such as OpenAI Codex, Google Jules, Claude Code, etc. The TypeScript implementation is an ideal task, thanks to existing tests.
+
+Below is the prompt:
+
+```
+Convert JSON Schemas into TS interfaces similar to what is in Python with datamodel-codegen. See https://github.com/bcherny/json-schema-to-typescript and https://github.com/ThomasAribart/json-schema-to-ts. Compare the two and choose the best option.
+
+The interfaces MUST BE generated programmatically, just as how we do in Python. Understand the directory structure first, list, navigate and read files. Look at the json schema files under /schema, and compare them with the generated files in the python directory
+
+We basically need to implement parsing of a JSON-DOC file into typed objects in typescript, similar to Python load_jsondoc() and similar functions
+
+Note that we use uv for running python. There are example json-doc files and tests under /tests and github actions that make sure that the parsing and validation logic in python is correct
+
+For a correct ts implementation, similar tests and checks need to be implemented. Make sure to use up-to-date typescript tooling and conventions. This library is supposed to be installed universally, keep that in mind. Do not use obscure or non-general tooling for packaging and distribution. Follow today's best practices
+```

docs/2025-05-22-ts-renderer-prompt.md

@@ -0,0 +1,37 @@
+---
+title: "Implementing JSON-DOC TypeScript parser"
+author: "Onur <[email protected]>"
+date: "2025-05-21"
+---
+
+We have previously implemented a TypeScript renderer for JSON-DOC, a new JSON based file format for documents. The excerpt below shows our initial intentions.
+
+---
+
+Convert JSON Schemas into TS interfaces similar to what is in Python with datamodel-codegen. See https://github.com/bcherny/json-schema-to-typescript and https://github.com/ThomasAribart/json-schema-to-ts. Compare the two and choose the best option.
+
+The interfaces MUST BE generated programmatically, just as how we do in Python. Understand the directory structure first, list, navigate and read files. Look at the json schema files under /schema, and compare them with the generated files in the python directory
+
+We basically need to implement parsing of a JSON-DOC file into typed objects in typescript, similar to Python load_jsondoc() and similar functions
+
+Note that we use uv for running python. There are example json-doc files and tests under /tests and github actions that make sure that the parsing and validation logic in python is correct
+
+For a correct ts implementation, similar tests and checks need to be implemented. Make sure to use up-to-date typescript tooling and conventions. This library is supposed to be installed universally, keep that in mind. Do not use obscure or non-general tooling for packaging and distribution. Follow today's best practices
+
+---
+
+This was implemented successfully, and now the tests for serialization and parsing passes. The next step is to implement a React TypeScript renderer for this file format. Implement a React component that will receive a JSON-DOC object and render it in the same visual style as Notion documents. You need to write logic to map each JSON-DOC block into HTML elements.
+
+To aid your process, I have included HTML elements and CSS files from Notion under /examples/notion/frontend. notion_frame1.html contains a Notion page with a lot of different block types, and notion_frame1_reduced.html contains the same page, but with certain information truncated to make it easier to see the structure and fit into the context.
+
+You don't need to match the style exactly, but you need to write code that will render each block at least in a logical and consistent way. Note that blocks can include other blocks recursively.
+
+IMPORTANT: YOU WILL AT NO CIRCUMSTANCE SKIP THE TASK OF RENDERING BLOCKS RECURSIVELY. BLOCKS CAN CONTAIN OTHER BLOCKS AT AN ARBITRARY DEPTH.
+
+YOU WILL RENDER ALL BLOCK TYPES THAT JSON-DOC SUPPORTS.
+
+For your test, you will be making sure that /schema/page/ex1_success.json is rendered correctly with this new React component.
+
+Look at README and CLAUDE.md files for more information. The Python implementation is the single source of truth for the JSON-DOC format. The TypeScript implementation was generated from the Python implementation, so it might contain some errors. If you encounter any errors or inconsistencies, fix them.
+
+TAKING SHORTCUTS WILL BE PENALIZED HEAVILY.