[PR #48] [CLOSED] Entrepeneur4lyf/fonts and api docs #250

New issue

Closed

opened 2026-03-02 23:45:36 +03:00 by kerem · 0 comments

kerem commented

2026-03-02 23:45:36 +03:00

Owner

📋 Pull Request Information

Original PR: https://github.com/anomalyco/opentui/pull/48
Author: @entrepeneur4lyf
Created: 8/20/2025
Status: ❌ Closed

Base: main ← Head: entrepeneur4lyf/fonts_and_api_docs

📝 Commits (4)

9c0e2b6 feat: add support for custom ASCII fonts via FontDefinition
e4f0230 fix: update React ASCII example to use FontDefinition
71e0f9c feat: add font validation and error handling
2ec68d3 Merge upstream/main and resolve import path conflicts

📊 Changes

50 files changed (+17427 additions, -40 deletions)

View changed files

➕ CLAUDE.md (+78 -0)
➕ packages/core/docs/api/3d/canvas.md (+126 -0)
➕ packages/core/docs/api/3d/exploding-sprite-effect.md (+120 -0)
➕ packages/core/docs/api/3d/physics-exploding-sprite-effect.md (+122 -0)
➕ packages/core/docs/api/3d/physics.md (+454 -0)
➕ packages/core/docs/api/3d/shaders.md (+874 -0)
➕ packages/core/docs/api/3d/sprite-animation.md (+518 -0)
➕ packages/core/docs/api/3d/sprite-animator.md (+115 -0)
➕ packages/core/docs/api/3d/sprites.md (+192 -0)
➕ packages/core/docs/api/3d/webgpu.md (+452 -0)
➕ packages/core/docs/api/3d/wgpu-renderer.md (+161 -0)
➕ packages/core/docs/api/README.md (+121 -0)
➕ packages/core/docs/api/advanced/3d.md (+854 -0)
➕ packages/core/docs/api/animation/animation.md (+761 -0)
➕ packages/core/docs/api/animation/timeline.md (+356 -0)
➕ packages/core/docs/api/buffer.md (+159 -0)
➕ packages/core/docs/api/components/ascii-font.md (+399 -0)
➕ packages/core/docs/api/components/box.md (+270 -0)
➕ packages/core/docs/api/components/framebuffer.md (+394 -0)
➕ packages/core/docs/api/components/group.md (+358 -0)

...and 30 more files

📄 Description

Add Custom Font Support and Comprehensive API Documentation

Custom ASCII Font Support

This PR adds the ability to use custom ASCII fonts with the ASCIIFontRenderable component. Users can now import any cfont-compatible JSON font file and use it directly.

Key Changes

Exported FontDefinition type - Makes the font structure public for TypeScript users
Clean API design - All font parameters now accept FontDefinition objects (no union types as requested)
Font validation - Added validateFontDefinition() function with detailed error messages
Built-in fonts accessible via fonts object - fonts.tiny, fonts.block, fonts.shade, fonts.slick

Usage

// Using built-in fonts
import { ASCIIFontRenderable, fonts } from '@opentui/core';

const text = new ASCIIFontRenderable('text', {
  text: 'HELLO',
  font: fonts.block
});

// Using custom fonts
import customFont from './my-custom-font.json';

const customText = new ASCIIFontRenderable('custom', {
  text: 'CUSTOM',
  font: customFont as FontDefinition
});

Breaking Changes

Font parameters no longer accept string names (e.g., "block"), must use FontDefinition objects
Updated React example to use new API

Comprehensive API Documentation

Added extensive API documentation for the core package in packages/core/docs/api/:

Documentation Structure

/components/ - Documentation for all renderable components
- renderables.md - Complete Renderable base class and all built-in components
- Individual component docs (box, text, input, select, etc.)
/core/ - Core rendering system
- rendering.md - CliRenderer API, events, configuration, lifecycle methods
/lib/ - Library utilities
- border.md, styled-text.md, selection.md, etc.
/animation/ - Animation system
- timeline.md - Timeline API for animations
Other sections - 3D capabilities, post-processing, utilities

Documentation Highlights

Complete API references with TypeScript interfaces
Practical code examples for every component
Event handling documentation
Configuration options and best practices
Custom component creation guides

Examples Added

custom-font-demo.ts - Demonstrates using built-in fonts
external-font-demo.ts - Shows importing and using custom fonts
font-validation-demo.ts - Tests font validation with invalid formats
grid-font.json - Sample custom font for testing

Testing

Validated font loading with external cfont files
Tested validation catches malformed fonts correctly
React example updated and working with new API
All demos render correctly in terminal

Technical Details

Leverages Bun's native JSON loader for zero-overhead font imports
Font definitions cached after first parse for performance
Validation runs once per unique font to catch errors early
Proper TypeScript types throughout

Note: This is a work in progress.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/anomalyco/opentui/pull/48 **Author:** [@entrepeneur4lyf](https://github.com/entrepeneur4lyf) **Created:** 8/20/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `entrepeneur4lyf/fonts_and_api_docs` --- ### 📝 Commits (4) - [`9c0e2b6`](https://github.com/anomalyco/opentui/commit/9c0e2b650335286ca3ac7ef64bb3b77edfefb85b) feat: add support for custom ASCII fonts via FontDefinition - [`e4f0230`](https://github.com/anomalyco/opentui/commit/e4f02305db2945c7eb3ede3c5eac3a646b2827bf) fix: update React ASCII example to use FontDefinition - [`71e0f9c`](https://github.com/anomalyco/opentui/commit/71e0f9c47499b2642472e0f887e7708434a90956) feat: add font validation and error handling - [`2ec68d3`](https://github.com/anomalyco/opentui/commit/2ec68d31e9d80fbd92c977188e4d90188941e652) Merge upstream/main and resolve import path conflicts ### 📊 Changes **50 files changed** (+17427 additions, -40 deletions) <details> <summary>View changed files</summary> ➕ `CLAUDE.md` (+78 -0) ➕ `packages/core/docs/api/3d/canvas.md` (+126 -0) ➕ `packages/core/docs/api/3d/exploding-sprite-effect.md` (+120 -0) ➕ `packages/core/docs/api/3d/physics-exploding-sprite-effect.md` (+122 -0) ➕ `packages/core/docs/api/3d/physics.md` (+454 -0) ➕ `packages/core/docs/api/3d/shaders.md` (+874 -0) ➕ `packages/core/docs/api/3d/sprite-animation.md` (+518 -0) ➕ `packages/core/docs/api/3d/sprite-animator.md` (+115 -0) ➕ `packages/core/docs/api/3d/sprites.md` (+192 -0) ➕ `packages/core/docs/api/3d/webgpu.md` (+452 -0) ➕ `packages/core/docs/api/3d/wgpu-renderer.md` (+161 -0) ➕ `packages/core/docs/api/README.md` (+121 -0) ➕ `packages/core/docs/api/advanced/3d.md` (+854 -0) ➕ `packages/core/docs/api/animation/animation.md` (+761 -0) ➕ `packages/core/docs/api/animation/timeline.md` (+356 -0) ➕ `packages/core/docs/api/buffer.md` (+159 -0) ➕ `packages/core/docs/api/components/ascii-font.md` (+399 -0) ➕ `packages/core/docs/api/components/box.md` (+270 -0) ➕ `packages/core/docs/api/components/framebuffer.md` (+394 -0) ➕ `packages/core/docs/api/components/group.md` (+358 -0) _...and 30 more files_ </details> ### 📄 Description # Add Custom Font Support and Comprehensive API Documentation ## Custom ASCII Font Support This PR adds the ability to use custom ASCII fonts with the ASCIIFontRenderable component. Users can now import any cfont-compatible JSON font file and use it directly. ### Key Changes - **Exported FontDefinition type** - Makes the font structure public for TypeScript users - **Clean API design** - All font parameters now accept FontDefinition objects (no union types as requested) - **Font validation** - Added validateFontDefinition() function with detailed error messages - **Built-in fonts accessible via fonts object** - fonts.tiny, fonts.block, fonts.shade, fonts.slick ### Usage ```typescript // Using built-in fonts import { ASCIIFontRenderable, fonts } from '@opentui/core'; const text = new ASCIIFontRenderable('text', { text: 'HELLO', font: fonts.block }); // Using custom fonts import customFont from './my-custom-font.json'; const customText = new ASCIIFontRenderable('custom', { text: 'CUSTOM', font: customFont as FontDefinition }); ``` ### Breaking Changes - Font parameters no longer accept string names (e.g., "block"), must use FontDefinition objects - Updated React example to use new API ## Comprehensive API Documentation Added extensive API documentation for the core package in packages/core/docs/api/: ### Documentation Structure - **/components/** - Documentation for all renderable components - renderables.md - Complete Renderable base class and all built-in components - Individual component docs (box, text, input, select, etc.) - **/core/** - Core rendering system - rendering.md - CliRenderer API, events, configuration, lifecycle methods - **/lib/** - Library utilities - border.md, styled-text.md, selection.md, etc. - **/animation/** - Animation system - timeline.md - Timeline API for animations - **Other sections** - 3D capabilities, post-processing, utilities ### Documentation Highlights - Complete API references with TypeScript interfaces - Practical code examples for every component - Event handling documentation - Configuration options and best practices - Custom component creation guides ## Examples Added - custom-font-demo.ts - Demonstrates using built-in fonts - external-font-demo.ts - Shows importing and using custom fonts - font-validation-demo.ts - Tests font validation with invalid formats - grid-font.json - Sample custom font for testing ## Testing - Validated font loading with external cfont files - Tested validation catches malformed fonts correctly - React example updated and working with new API - All demos render correctly in terminal ## Technical Details - Leverages Bun's native JSON loader for zero-overhead font imports - Font definitions cached after first parse for performance - Validation runs once per unique font to catch errors early - Proper TypeScript types throughout Note: This is a work in progress. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>