{"id":31213740,"url":"https://github.com/itsjess1ca/zonr-core","last_synced_at":"2026-04-17T09:31:21.173Z","repository":{"id":314616038,"uuid":"1052950683","full_name":"itsJess1ca/Zonr-Core","owner":"itsJess1ca","description":"A modern TypeScript library for building organized, dynamic terminal interfaces with zone-based layouts","archived":false,"fork":false,"pushed_at":"2025-09-13T17:56:42.000Z","size":10046,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-13T19:29:10.490Z","etag":null,"topics":["ansi-rendering","cli-tools","command-line","cross-platform","dashboard-builder","developer-tools","event-driven","layout-engine","multi-zone","nodejs","progress-bars","real-time-ui","responsive-terminal","terminal-interface","terminal-ui","typescript","windows-compatible","zone-layout"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itsJess1ca.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-08T19:20:17.000Z","updated_at":"2025-09-13T17:56:44.000Z","dependencies_parsed_at":"2025-09-13T19:29:11.658Z","dependency_job_id":null,"html_url":"https://github.com/itsJess1ca/Zonr-Core","commit_stats":null,"previous_names":["itsjess1ca/zonr","itsjess1ca/zonr-core"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/itsJess1ca/Zonr-Core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsJess1ca%2FZonr-Core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsJess1ca%2FZonr-Core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsJess1ca%2FZonr-Core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsJess1ca%2FZonr-Core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itsJess1ca","download_url":"https://codeload.github.com/itsJess1ca/Zonr-Core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itsJess1ca%2FZonr-Core/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276210448,"owners_count":25603724,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-21T02:00:07.055Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi-rendering","cli-tools","command-line","cross-platform","dashboard-builder","developer-tools","event-driven","layout-engine","multi-zone","nodejs","progress-bars","real-time-ui","responsive-terminal","terminal-interface","terminal-ui","typescript","windows-compatible","zone-layout"],"created_at":"2025-09-21T08:17:39.456Z","updated_at":"2025-09-21T08:17:42.090Z","avatar_url":"https://github.com/itsJess1ca.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\r\n\r\n![Zonr Logo](public/full.svg)\r\n\r\n\u003c/div\u003e\r\n\r\n\u003e A modern TypeScript library for building organized, dynamic terminal interfaces with zone-based layouts\r\n\r\n[![npm version](https://badge.fury.io/js/@zonr-logs%2Fcore.svg)](https://badge.fury.io/js/@zonr-logs%2Fcore)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![Node.js Version](https://img.shields.io/node/v/@zonr-logs%2Fcore.svg)](https://nodejs.org/)\r\n\r\n---\r\n\r\n![Hero Demo GIF](public/playground.gif)\r\n\r\nZonr transforms terminal output from chaotic text streams into organized, responsive interfaces. Create dashboards, build tools, monitoring systems, and interactive applications with intuitive zone-based layouts that adapt to your terminal size.\r\n\r\n---\r\n\r\n## ✨ Key Features\r\n\r\n- **🎯 Zone-Based Architecture**: Organize output into distinct, configurable areas\r\n- **📐 Dynamic Layout System**: Automatic row grouping with intelligent space distribution  \r\n- **📱 Responsive Design**: Zones adapt automatically to terminal size changes\r\n- **⚡ Real-Time Updates**: Event-driven messaging for instant UI updates\r\n- **🎨 Customizable Styling**: Configurable borders, colors, headers, and dimensions\r\n- **🔧 Perfect Alignment**: Custom ANSI renderer ensures pixel-perfect borders\r\n- **🌍 Wide Character Support**: Proper handling of emoji and Unicode characters\r\n- **🚀 High Performance**: Differential rendering updates only changed content\r\n- **🪟 Cross-Platform**: Full Windows support with resize detection workarounds\r\n- **📁 File Transport**: High-performance logging with sonic-boom and automatic cleanup\r\n- **🛡️ Signal Handling**: Automatic graceful shutdown with transport flushing on SIGINT/SIGTERM\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\nnpm install @zonr-logs/core\r\n# or\r\npnpm add @zonr-logs/core  \r\n# or\r\nyarn add @zonr-logs/core\r\n```\r\n\r\n**Requirements:** Node.js ≥16\r\n\r\n---\r\n\r\n## 🎮 Quick Start\r\n\r\n```typescript\r\nimport Zonr, { FileTransport } from '@zonr-logs/core';\r\n\r\n// Create a new terminal UI with automatic signal handling\r\nconst zonr = new Zonr({ autoCleanup: true });\r\n\r\n// Add zones with different layouts and file logging\r\nconst logs = zonr.addZone({\r\n  name: \"Application Logs\",\r\n  width: \"70%\",\r\n  height: \"auto\", \r\n  borderColor: \"blue\",\r\n  additionalTransports: [\r\n    new FileTransport({\r\n      filePath: \"./app.log\",\r\n      highVolume: true  // Optimized for high-throughput logging\r\n    })\r\n  ]\r\n});\r\n\r\nconst status = zonr.addZone({\r\n  name: \"System Status\",\r\n  width: \"30%\", \r\n  height: \"auto\",\r\n  borderColor: \"green\"\r\n});\r\n\r\n// Start logging - automatically flushes to file on exit\r\nlogs.info('🚀 Application started');\r\nlogs.warn('⚠️  High memory usage detected');\r\nlogs.error('❌ Database connection failed');\r\n\r\nstatus.info('✅ Server: Online');\r\nstatus.info('📊 CPU: 45%'); \r\nstatus.info('💾 Memory: 2.1GB');\r\n```\r\n\r\n---\r\n\r\n## 🎬 Demo Gallery\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e🚀 Playground Demo\u003c/b\u003e - Basic file processing with progress tracking\u003c/summary\u003e\r\n\r\nThe main playground demonstration showing file processing with real-time progress bars, metadata tracking, and logging.\r\n\r\n```bash\r\npnpm run playground\r\n```\r\n\r\n*Features: Progress bars, batch processing, real-time metrics, file logging*\r\n\r\n![Hero Demo GIF](public/playground.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e📊 Minimal Dashboard\u003c/b\u003e - Simple two-zone layout\u003c/summary\u003e\r\n\r\nClean, minimal interface demonstrating basic zone creation with application logs and system status.\r\n\r\n```bash\r\npnpm run demo:minimal\r\n```\r\n\r\n*Features: Basic layouts, log levels, system metrics, auto-updating status*\r\n\r\n![Demo Minimal GIF](public/demo-minimal.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e🎮 Gaming Interface Demo\u003c/b\u003e - Multi-zone gaming server monitor\u003c/summary\u003e\r\n\r\nComprehensive gaming server monitoring interface with player activity, server stats, game events, and match results.\r\n\r\n```bash\r\npnpm run demo:gaming\r\n```\r\n\r\n*Features: Multi-zone layout, real-time stats, emoji rendering, leaderboards*\r\n\r\n![Gaming Demo GIF](public/demo-gaming.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e🔧 Build System Monitor\u003c/b\u003e - Complex build pipeline visualization\u003c/summary\u003e\r\n\r\nAdvanced build pipeline demonstration with progress tracking, build logs, test results, and deployment status.\r\n\r\n```bash\r\npnpm run demo:build\r\n```\r\n\r\n*Features: Build stages, progress indicators, test results, deployment tracking*\r\n\r\n![Build Demo GIF](public/demo-build.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e📈 Data Processing Dashboard\u003c/b\u003e - Real-time data pipeline\u003c/summary\u003e\r\n\r\nReal-time data processing pipeline with input queues, processing steps, output results, and performance metrics.\r\n\r\n```bash\r\npnpm run demo:data\r\n```\r\n\r\n*Features: Queue management, processing analytics, throughput metrics, auto-height zones*\r\n\r\n![Data Demo GIF](public/demo-data.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n\u003cdetails\u003e\r\n\u003csummary\u003e\u003cb\u003e🖥️ Full Development Dashboard\u003c/b\u003e - Complete monitoring interface\u003c/summary\u003e\r\n\r\nComprehensive developer monitoring interface with system metrics, application logs, alerts, and status indicators.\r\n\r\n```bash\r\npnpm run demo:dashboard\r\n```\r\n\r\n*Features: System monitoring, log aggregation, alert management, comprehensive layouts*\r\n\r\n![Dashboard Demo GIF](public/demo-dashboard.gif)\r\n\r\n\u003c/details\u003e\r\n\r\n---\r\n\r\n## 📚 API Reference\r\n\r\n### Creating a Zonr Instance\r\n\r\n```typescript\r\nimport Zonr from '@zonr-logs/core';\r\n\r\nconst zonr = new Zonr();\r\n```\r\n\r\n### Adding Zones\r\n\r\n```typescript\r\nconst zone = zonr.addZone({\r\n  name: string,           // Zone header text\r\n  width: string | number, // \"50%\", \"auto\", or pixel value\r\n  height: string | number,// \"auto\", \"50%\", or pixel value  \r\n  borderColor?: string,   // \"red\", \"blue\", \"green\", etc.\r\n  showHeader?: boolean,   // Show/hide zone header\r\n  showBorder?: boolean    // Show/hide zone borders\r\n});\r\n```\r\n\r\n### Zone Methods\r\n\r\n```typescript\r\n// Logging methods\r\nzone.info(message: string)    // Blue info message\r\nzone.warn(message: string)    // Yellow warning message  \r\nzone.error(message: string)   // Red error message\r\nzone.debug(message: string)   // Gray debug message\r\nzone.log(message: string)     // Default log message\r\n\r\n// Zone management\r\nzone.clear()                  // Clear all messages\r\nzone.getName()               // Get zone name\r\nzone.getConfig()             // Get zone configuration\r\n```\r\n\r\n### Zone Management\r\n\r\n```typescript\r\n// Zone management methods\r\nzonr.addZone(config)         // Add a new zone\r\nzonr.getZone(name)           // Find zone by name\r\nzonr.hasZone(name)           // Check if zone exists\r\nzonr.getAllZones()           // Get all zones array\r\nzonr.removeZone(nameOrZone)  // Remove specific zone by name or reference\r\nzonr.clearZones()            // Remove all zones\r\n\r\n// Legacy API still available\r\nzonr.zones.add(config)       // Same as zonr.addZone()\r\nzonr.zones.get(name)         // Same as zonr.getZone()\r\nzonr.zones.list()            // Same as zonr.getAllZones()\r\n```\r\n\r\n### Layout Configuration\r\n\r\n```typescript\r\n// Width options\r\nwidth: \"50%\"        // Percentage of terminal width\r\nwidth: \"auto\"       // Automatic width distribution\r\nwidth: 80           // Fixed pixel width\r\n\r\n// Height options  \r\nheight: \"auto\"      // Adapts to terminal size and content\r\nheight: \"30%\"       // Percentage of terminal height\r\nheight: 20          // Fixed row height\r\n\r\n// Color options\r\nborderColor: \"black\" | \"red\" | \"green\" | \"yellow\" | \"blue\" | \"magenta\" | \"cyan\" | \"white\" | \"gray\"\r\n```\r\n\r\n---\r\n\r\n## 🎯 Use Cases\r\n\r\n### Development Tools\r\n- **Build Monitors**: Track compilation, testing, and deployment stages\r\n- **Log Aggregation**: Organize application logs by service or severity\r\n- **Development Servers**: Show multiple service statuses simultaneously\r\n\r\n### System Monitoring  \r\n- **Server Dashboards**: Display metrics, alerts, and system health\r\n- **Process Monitoring**: Track multiple running processes and their output\r\n- **Network Tools**: Monitor connections, throughput, and diagnostics\r\n\r\n### Interactive Applications\r\n- **Gaming Interfaces**: Leaderboards, chat, game state visualization  \r\n- **CLI Tools**: Multi-step workflows with progress tracking\r\n- **Data Processing**: Real-time pipeline monitoring and statistics\r\n\r\n---\r\n\r\n## 🔧 Advanced Usage\r\n\r\n### File Transport\r\n\r\n```typescript\r\nimport { FileTransport } from '@zonr-logs/core';\r\n\r\n// High-performance file logging with automatic cleanup\r\nconst fileTransport = new FileTransport({\r\n  filePath: './logs/app.log',        // Direct file path\r\n  highVolume: true,                  // Optimize for high-throughput logging\r\n  maxFiles: 5,                       // File rotation (placeholder)\r\n  maxSize: '100MB'                   // Size rotation (placeholder)\r\n});\r\n\r\n// Alternative: path + filename pattern\r\nconst altTransport = new FileTransport({\r\n  path: './logs',                    // Directory path\r\n  filename: 'application.log',       // Filename\r\n  sync: true,                        // Synchronous writes for reliability\r\n  minLength: 8192                    // Buffer size for performance\r\n});\r\n\r\nconst zone = zonr.addZone({\r\n  name: \"Persistent Logs\",\r\n  width: \"100%\",\r\n  height: \"auto\",\r\n  additionalTransports: [fileTransport]  // Updated property name\r\n});\r\n\r\n// Automatic transport cleanup on SIGINT/SIGTERM\r\n// Files are properly flushed and closed when process exits\r\n```\r\n\r\n### Event-Driven Updates\r\n\r\n```typescript\r\n// Zones automatically emit events for real-time updates\r\nzone.info('Processing started...');\r\n\r\n// Updates are immediately reflected in the terminal\r\nsetTimeout(() =\u003e {\r\n  zone.info('Processing completed ✅');\r\n}, 2000);\r\n```\r\n\r\n### Automatic Signal Handling\r\n\r\n```typescript\r\n// Create Zonr instance with automatic cleanup (default: true)\r\nconst zonr = new Zonr({ autoCleanup: true });\r\n\r\n// Add zones with file transports\r\nconst logger = zonr.addZone({\r\n  name: \"Application\",\r\n  additionalTransports: [\r\n    new FileTransport({ filePath: './app.log' })\r\n  ]\r\n});\r\n\r\nlogger.info('Application started');\r\n\r\n// When user presses Ctrl+C or process receives SIGTERM:\r\n// 1. All transports are automatically flushed\r\n// 2. All transports are properly closed  \r\n// 3. Process exits gracefully\r\n// 4. No data is lost!\r\n\r\n// Disable automatic cleanup if needed\r\nconst manualZonr = new Zonr({ autoCleanup: false });\r\n// You would need to manually call:\r\n// await manualZonr.flushAllTransports();\r\n// await manualZonr.closeAllTransports();\r\n```\r\n\r\n### Dynamic Layout Changes\r\n\r\n```typescript\r\n// Zones automatically reflow when terminal is resized\r\n// No additional code needed - Zonr handles it automatically!\r\n\r\n// Works perfectly on Windows with built-in resize detection\r\n```\r\n\r\n---\r\n\r\n## 🏗️ Architecture\r\n\r\nZonr uses a custom ANSI-based rendering system that provides:\r\n\r\n- **Direct Terminal Control**: Precise cursor positioning and screen management\r\n- **Differential Updates**: Only redraws changed content to eliminate flicker\r\n- **Layout Engine**: Sophisticated algorithm for space distribution and row grouping\r\n- **Event System**: Real-time communication between zones and renderer\r\n- **Windows Compatibility**: Specialized handling for Windows terminal limitations\r\n\r\n### Key Components\r\n\r\n- **Zonr Class**: Main facade providing the public API\r\n- **Zone Manager**: Handles zone lifecycle and organization  \r\n- **Layout Calculator**: Dynamic space allocation and row grouping\r\n- **Custom Renderer**: ANSI-based rendering with perfect border alignment\r\n- **Transport System**: Pluggable output destinations (terminal, file, etc.)\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\r\n\r\n### Development Setup\r\n\r\n```bash\r\n# Clone the repository  \r\ngit clone https://github.com/itsJess1ca/Zonr-Core.git\r\ncd zonr\r\n\r\n# Install dependencies\r\npnpm install\r\n\r\n# Run tests\r\npnpm test\r\n\r\n# Build the project\r\npnpm build\r\n\r\n# Try the demos\r\npnpm run demo:minimal\r\npnpm run demo:gaming\r\n```\r\n\r\n### Conventional Commits\r\n\r\nThis project uses [Conventional Commits](https://www.conventionalcommits.org/) with automated semantic versioning:\r\n\r\n```bash\r\n# Interactive commit prompts (recommended)\r\npnpm run commit\r\n\r\n# Manual conventional format\r\ngit commit -m \"feat: add new zone layout algorithm\"\r\ngit commit -m \"fix: resolve border alignment issue\" \r\ngit commit -m \"docs: update API documentation\"\r\n\r\n# Test what would be released\r\npnpm run release:dry\r\n```\r\n\r\n**Commit Types:**\r\n- `feat:` - New features (minor version bump)\r\n- `fix:` - Bug fixes (patch version bump)\r\n- `docs:` - Documentation changes\r\n- `style:` - Code style changes\r\n- `refactor:` - Code refactoring\r\n- `test:` - Adding or updating tests\r\n- `chore:` - Maintenance tasks\r\n- `ci:` - CI/CD changes\r\n- `perf:` - Performance improvements\r\n- `build:` - Build system changes\r\n\r\n**Breaking Changes:** Add `BREAKING CHANGE:` in commit footer for major version bumps.\r\n\r\n**Automated Releases:** Semantic releases are automatically created when conventional commits are pushed to the main branch.\r\n\r\n### Running Tests\r\n\r\n```bash\r\npnpm test           # Run tests in watch mode\r\npnpm test:run       # Run tests once\r\npnpm test:ui        # Run tests with UI\r\n```\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details\r\n\r\n---\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- Built with TypeScript for excellent developer experience\r\n- Inspired by modern terminal UI libraries but designed for simplicity\r\n- Special thanks to the Node.js community for terminal handling insights\r\n\r\n---\r\n\r\n## 📞 Support\r\n\r\n- 🐛 **Issues**: [GitHub Issues](https://github.com/itsJess1ca/Zonr-Core/issues)\r\n- 💬 **Discussions**: [GitHub Discussions](https://github.com/itsJess1ca/Zonr-Core/discussions)\r\n- 📧 **Email**: jessica.ide247@gmail.com\r\n\r\n---\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\r\n**[⭐ Give us a star on GitHub!](https://github.com/itsJess1ca/Zonr-Core)**\r\n\r\nMade with ❤️ for the terminal-loving community\r\n\r\n\u003c/div\u003e\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsjess1ca%2Fzonr-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitsjess1ca%2Fzonr-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitsjess1ca%2Fzonr-core/lists"}