calx-react

What is calx-react?

calx-react is a React-based UI builder for CalX OS that renders on configurable monochrome displays (default 128x64 pixels).

How does it work?

function App() {
  return (
    <Text>Hello, world!</Text>
  );
}

calx.render(<App />, calx.device.screen);

This converts the text "Hello, world!" into pixels and sends an array of pixels to the device screen.

The output for the default screen (128x64) would look like this:

[[1,0,0,1,0,0,1...], [1,0,0,1,0,0,1...], ...]

The device would then render it on the screen, displaying "Hello, world!" in a 3x5 pixel font.

Screen Configuration

The default screen size is 128x64 pixels, but this can be configured:

import { SCREEN } from 'calx-react';

// Check current screen dimensions
console.log(`Screen: ${SCREEN.WIDTH}x${SCREEN.HEIGHT}`);

// Use custom screen size
const customBuffer = new PixelBuffer(256, 128); // 256x128 screen

Getting Started

Installation

# Install dependencies
bun install

Using the Virtual Screen

For development and testing, use the VirtualScreen class that logs output to the console:

import { render, Text, VirtualScreen } from 'calx-react';

const screen = new VirtualScreen('my-screen');

function App() {
  return <Text>Hello, CalX!</Text>;
}

render(<App />, screen);

Running Examples

The examples/ folder contains sample applications:

# Run basic example with text and pixel art
cd examples
bun run basic

# Run interactive example with drawing and calculator
bun run interactive

Example Applications

Basic Text and Graphics

function App() {
  return (
    <>
      <Text x={10} y={10}>Hello, CalX!</Text>
      <Pixels coordinates={[[64, 32], [65, 32], [66, 32]]} />
    </>
  );
}

Manual State Updates

Since this is a simplified renderer, state updates require manual re-rendering:

let counter = 0;

function updateCounter() {
  counter++;
  render(<Text>Count: {counter}</Text>, screen);
}

// Update every second
setInterval(updateCounter, 1000);

Important Notes

• No automatic re-rendering: Unlike full React, state changes don't automatically trigger re-renders
• Manual updates: Call render() again to update the display
• Functional components: Supports functional components and JSX
• No hooks: useState, useEffect etc. are not supported in this simplified version

Supported Characters

The Text component supports a complete character set:

Uppercase Letters

A-Z (full alphabet)

Lowercase Letters

a-z (full alphabet)

Numbers

0-9

Symbols

! ? . , : ; ' " - + = * / \ | ( ) [ ] { } < > @ # $ % & ^ _ ` ~

Usage Example

function App() {
  return (
    <>
      <Text x={0} y={0}>UPPERCASE: ABCDEFGHIJKLMNOPQRSTUVWXYZ</Text>
      <Text x={0} y={8}>lowercase: abcdefghijklmnopqrstuvwxyz</Text>
      <Text x={0} y={16}>Numbers: 0123456789</Text>
      <Text x={0} y={24}>Symbols: !@#$%^&*()_+-={}[]|;':",./<>?</Text>
    </>
  );
}

Each character is rendered in a 3x5 pixel grid with 1 pixel spacing between characters.

Development

Project Structure

calx-react/
├── src/
│   ├── types.ts           # Type definitions
│   ├── pixel-buffer.ts    # Pixel buffer management
│   ├── component-registry.ts # Component system
│   ├── simple-renderer.ts # Simple React renderer
│   └── virtual-screen.ts  # Development screen
├── components/
│   ├── pixels.tsx         # Pixels component
│   └── text.tsx          # Text component
├── examples/
│   ├── basic-example.tsx  # Basic usage examples
│   └── interactive-example.tsx # Interactive demos
└── index.ts              # Main exports

Virtual Screen API

const screen = new VirtualScreen('screen-id');

// Send pixels (automatically called by render)
screen.send(pixels);

// Clear screen
screen.clear();

// Get last rendered pixels
const lastPixels = screen.getLastPixels();

// Get rendering statistics
const stats = screen.getPixelStats();
// Returns: { totalPixels: 8192, onPixels: 245, offPixels: 7947 }