Commit Graph
11 Commits
Author SHA1 Message Date
LGUG2Z 6bf0975898 test(jsonschema): add index.html for test suite outputs
Add functionality to generate an index.html file after running the
JSON Schema Test Suite integration tests, providing easy navigation
of generated documentation.

Features:
- Use Tera template (test_index.html) for consistent styling
- Display statistics: total schemas, test files, with/without content
- Annotate each schema with content status (has properties/$defs or not)
- Show JSON Schema features/keywords used in each test schema
- Include build information: git commit hash, dirty status, timestamps
- Group schemas by source test file for easy navigation
2025-12-22 10:23:12 -08:00
LGUG2Z 2e3913c325 test(jsonschema): add json schema test suite compat tests
Add comprehensive integration tests using the official JSON-Schema-Test-Suite
draft2020-12 examples to ensure the CLI handles all valid JSON Schema constructs
without crashing.

Changes:
- Add 80 fixture files from JSON-Schema-Test-Suite draft2020-12
- Add parallelized integration test that runs CLI against all 448 schemas
- Normalize non-standard $ref patterns (root refs, JSON pointers, external URIs)
- Decode URL-encoded and JSON pointer escaped characters in $ref paths
- Embed type usages directly in $defs to avoid Tera lookup issues with
  special characters in definition names
- Handle missing $defs gracefully in template rendering

The test suite runs in ~5 seconds using Rayon for parallel execution.
2025-12-22 10:04:47 -08:00
LGUG2Z 25b4a8fae9 feat(docgen): add build-time css validation
Implement compile-time validation that all CSS class names defined in
identifiers.rs have corresponding styles in style.css.

Build Script Integration:
- Add build.rs with lightningcss for CSS parsing
- Parse style.css and extract all class selectors
- Iterate over CssClasses and TypeClasses using struct_iterable
- Fail build if any defined class lacks CSS rules

Runtime Test (backup validation):
- Add `test_all_css_classes_are_styled` in identifiers.rs
- Uses regex to extract class names from CSS file
- Verifies both CSS and TYPE_CLASSES are fully styled
- Allows dynamic prefixes like "depth-" that are generated at runtime

Struct Changes:
- Add `#[derive(Iterable)]` to CssClasses and TypeClasses
- Add `#[allow(dead_code)]` to IDS and HtmlIds (used by main, not build)

Cleanup:
- Remove unused CSS classes: `map_entries`, `too_deep`
- Remove corresponding entries from identifiers.rs

New Dependencies:
- lightningcss = "1.0.0-alpha.68" (build-dependency)
- struct_iterable = "0.1" (dependency and build-dependency)
- serde with derive (build-dependency for struct_iterable)

This ensures CSS/Rust synchronization is maintained and catches
missing styles before runtime.
2025-12-22 09:44:02 -08:00
LGUG2Z c46efde896 feat(css): add comprehensive mobile responsive styles
Add extensive CSS media queries and overflow handling for proper mobile
device display of generated documentation.

Overflow Prevention:
- Set `overflow-x: hidden` on body and main-content
- Add `word-break: break-word` and `overflow-wrap: anywhere` to property names
- Enable horizontal scrolling inside pre blocks and enum values
- Ensure code elements break properly on narrow screens

Mobile Layout Adjustments (148 lines):
- Reduce padding throughout (main-content, definition, description, usages)
- Smaller font sizes for headers, titles, and definition names
- Adjust modal sizing: full width, 90vh max height, reduced padding
- Compact nested schema containers (properties, array-items, variants)

Search Results Mobile:
- Flex-wrap enabled for search result items
- Result path takes full width with word breaking
- Reorder elements with CSS order property

Typography Scaling:
- Header h1: 1.25rem
- Schema section h2: 1.25rem
- Definition names: 1.1rem with word-break
- Modal title: 1rem

Component Spacing:
- Reduced gap in property-header
- Smaller margins on type badges and refs
- Compact constraints display (flex-direction: column)
- Reduced padding on nested-schema summaries
2025-12-22 09:31:29 -08:00
LGUG2Z ff0088e293 chore(deps): cargo update and remove unused dev-dependencies
Dependency Updates:
- Upgrade pulldown-cmark from 0.12 to 0.13
- Simplify version specifiers (e.g., "1.1" → "1", "1.19" → "1")

Removed Dependencies:
- Remove pretty_assertions dev-dependency (unused)
- Remove diff transitive dependency
- Remove yansi transitive dependency

Cargo.toml Changes:
- schemars: "1.1" → "1"
- serde: "1.0" → "1"
- serde_json: "1.0" → "1"
- tera: "1.19" → "1"
- pulldown-cmark: "0.12" → "0.13"
- Remove pretty_assertions = "1.4"
2025-12-22 09:31:29 -08:00
LGUG2Z c6835ddbb2 feat: add modal overlay for type definitions
Implement a modal popup system for viewing type definitions without leaving
the current context, with browser-like back/forward navigation.

Modal UI Components:
- Full-screen overlay with centered modal dialog
- Header with title, close button, and navigation controls
- Scrollable content area for type definition
- Back (←) and forward (→) navigation buttons
- Visual disabled state for navigation at history bounds

Navigation Features:
- Click any type reference in root schema to open in modal
- Click type references within modal to navigate deeper
- Keyboard shortcuts: Alt+← (back), Alt+→ (forward), Escape (close)
- History tracking with array and index pointer
- History resets on modal close

JavaScript Implementation:
- `openTypeModal(typeName, addToHistory)`: Open/navigate to type
- `showType(typeName)`: Clone and display type definition content
- `navigateHistory(direction)`: Handle back/forward navigation
- `closeModal()`: Close modal and reset state
- `updateNavButtons()`: Enable/disable nav buttons based on position

CSS Styling (102 lines added):
- `.modal-overlay`: Fixed positioning with semi-transparent background
- `.modal`: Centered container with max dimensions and shadow
- `.modal-header`: Flex layout for nav, title, and close button
- `.modal-nav-btn`: Styled navigation buttons with disabled state
- `.modal-content`: Scrollable content with padding

Identifier Updates:
- Add modal-related IDs and classes to identifiers.rs
- New ID: `modal-overlay`
- New classes: modal, modal-active, modal-header, modal-title, modal-close,
  modal-content, modal-nav, modal-nav-btn, disabled
2025-12-22 09:31:29 -08:00
LGUG2Z f32d94d929 fix(docgen): handle heterogeneous tuples
Fix template rendering for tuples (arrays with prefixItems) that contain
non-primitive types like $ref or anyOf, which were incorrectly detected
as homogeneous tuples.

Template Logic Fix:
- Check if `item.type` and `first_type.type` are both defined before comparing
- Treat items with $ref, anyOf, or missing type as heterogeneous
- Apply fix in all three locations: render_type_badge, render_array_items_inline,
  and render_array_items macros

Display Name Enhancement:
- Strip trailing digits from ALL type names, not just wrapper types
- Types like `DisplayFormat2` now display as `DisplayFormat`
- Only adds `_display_name` when it differs from original name
2025-12-22 09:31:29 -08:00
LGUG2Z 5d606f0d87 refactor(docgen): centralize css classes and html ids
Create a single source of truth for all CSS class names and HTML element IDs
used throughout the generated documentation.

New Module (`src/identifiers.rs`):
- `HtmlIds` struct: Static HTML IDs for JS interaction (search, sidebar, etc.)
- `CssClasses` struct: All CSS class names organized by category
- `TypeClasses` struct: Type-specific badge classes (type-string, type-integer, etc.)
- Constants `IDS`, `CSS`, `TYPE_CLASSES` for compile-time access
- Serializable via serde for use in Tera templates

Class Categories:
- Layout: header, layout, main-content
- Sidebar: sidebar, sidebar-open, sidebar-toggle, sidebar-section
- Navigation: nav-list, nav-link, outline-list, outline-item
- Search: search-container, search-results, search-result-item
- Schema: schema-section, properties-container, property, property-header
- Badges: badge, required, deprecated, optional
- Types: type-badge, type-ref, and all type-specific classes
- Nested: nested-schema, array-items, tuple-items, variants
- Definition: definition, definition-name, highlight, usages

Template Updates:
- Replace hardcoded class strings with `{{ css.class_name }}` references
- Replace hardcoded IDs with `{{ ids.id_name }}` references
- Enables IDE navigation and refactoring support

Also adds `schema.json` test fixture (komorebi configuration schema)
2025-12-22 09:31:29 -08:00
LGUG2Z 8d8780c427 fix(css): improve spacing consistency
Fix visual spacing issues between type badges, references, and other inline
elements in the generated documentation.

CSS Changes:
- Add `margin-left: 0.25rem` to `.badge`, `.type-badge`, and `.type-ref`
- Add `:first-child` selectors to remove left margin on first elements
- Ensures consistent spacing when multiple badges appear together

Template Fixes:
- Remove excess whitespace in Tera template conditionals
- Fix spacing around optional badges and type badges in `render_type_badge`
- Consolidate inline spacing in `render_schema` macro
- Clean up wrapper type inner badge rendering whitespace
2025-12-22 09:31:29 -08:00
LGUG2Z 7d4b7857bb feat(docgen): add wrapper type detection and improved tuple/float display
Implement intelligent detection of "wrapper types" (anyOf patterns with map
variant and inner type) to render them more meaningfully in documentation.

Wrapper Type Detection:
- Detect anyOf patterns like `[{object with additionalProperties: T}, T]`
- Mark detected wrappers with `_wrapper_type` and `_wrapper_inner` metadata
- Display inner type directly instead of showing misleading "enum" badge
- Link wrapper types to their inner type definitions
- Add `_display_name` field for wrapper types with numeric suffixes

Float Display Improvements:
- Display "float" instead of "number" for JSON Schema number types in tuples
- Use `type-float` CSS class for consistent styling
- Homogeneous tuples now show as "float; N" for number arrays

Navigation Enhancements:
- Build navigation from prepared schema (includes wrapper display names)
- Add `display_names` map to template context for type name resolution
- Track type usages for "Usages" section in definitions

Test Coverage:
- Add comprehensive tests for wrapper type rendering
- Test tuple float/integer display formatting
- Verify wrapper types don't show "Enum variants" dropdown
- Test non-wrapper anyOf still correctly shows enum badge
2025-12-22 09:31:29 -08:00
LGUG2Z c85edf242f feat(docgen): initial implementation of html doc generator
Implement a complete Rust library and CLI tool for generating self-contained
HTML documentation from schemars::Schema (JSON Schema) objects.

Core Features:
- Library API with `generate_html()` function and `Options` struct
- CLI binary accepting JSON Schema input files with optional title override
- Tera-based HTML templating with base template and reusable macros
- Markdown rendering for schema descriptions via pulldown-cmark
- Dark/light theme support following system preferences
- Searchable properties with instant search functionality
- Collapsible nested structures for complex schemas
- Responsive design for mobile, tablet, and desktop

Library Components:
- `generator.rs`: Main HTML generation logic with Tera template engine
- `prepare.rs`: Schema preprocessing for template rendering (1667 lines)
- `lib.rs`: Public API with SchemaExt trait for typed schema accessors
- `main.rs`: CLI interface using clap for argument parsing

Template System:
- `base.html`: Main HTML structure with header, sidebar, and content areas
- `macros.html`: Reusable Tera macros for rendering schema components
- `style.css`: Complete CSS with CSS variables for theming (955 lines)
2025-12-22 09:31:19 -08:00