@web-engine-dev/ui

Game UI framework with widgets, layouts, styling, and interaction support.

Note: Layout, text measurement, gesture handling, Canvas2D rendering, and WebGPU blit backend integration are implemented. Advanced accessibility beyond tree generation is still in progress.

Features

• Widget Library: Buttons, panels, labels, sliders, etc.
• Layout System: Flexbox-inspired layouts with scroll offsets + clipping
• Styling: CSS-like styling with themes
• Images: Intrinsic sizing via cached image dimensions (register sizes or use Canvas2D backend)
• Focus Management: Keyboard/gamepad navigation
• Animation: Tween-based UI animations
• Data Binding: Reactive state updates

Installation

npm install @web-engine-dev/ui
# or
pnpm add @web-engine-dev/ui

Quick Start

import { UICanvas, Panel, Button, Label, Column } from '@web-engine-dev/ui';

// Create UI canvas
const ui = new UICanvas(device);

// Build UI
const menu = new Panel({
  layout: new Column({ gap: 10, padding: 20 }),
  style: { background: '#333333', borderRadius: 8 },
  children: [
    new Label({ text: 'Main Menu', style: { fontSize: 32 } }),
    new Button({
      text: 'Play',
      onClick: () => startGame(),
    }),
    new Button({
      text: 'Options',
      onClick: () => showOptions(),
    }),
  ],
});

ui.add(menu);

// Update and render
ui.update(deltaTime);
ui.render();

API Overview

Widgets

// Label
new Label({ text: 'Hello', style: {...} });

// Button
new Button({
  text: 'Click Me',
  icon: iconTexture,
  onClick: () => {},
  onHover: () => {},
});

// Panel
new Panel({
  layout: new Column(),
  children: [...],
});

// Image
new Image({ texture: tex, fit: 'contain' });

// Slider
new Slider({
  min: 0, max: 100, value: 50,
  onChange: (v) => {},
});

// Checkbox
new Checkbox({
  checked: true,
  onChange: (v) => {},
});

// TextField
new TextField({
  placeholder: 'Enter text...',
  onChange: (v) => {},
});

Layouts

// Column (vertical stack)
new Column({ gap: 10, padding: 20, align: 'center' });

// Row (horizontal stack)
new Row({ gap: 10, justify: 'space-between' });

// Grid
new Grid({ columns: 3, gap: 10 });

// Anchor (position relative to parent)
new Anchor({
  anchor: 'center',
  offset: { x: 0, y: 0 },
});

Styling

const style = {
  background: '#333333',
  borderRadius: 8,
  border: '2px solid #666666',
  padding: 10,
  fontSize: 16,
  fontFamily: 'Arial',
  color: '#ffffff',
  shadow: '0 2px 4px #00000080',
};

// Hover/active states
const buttonStyle = {
  normal: { background: '#444' },
  hover: { background: '#555' },
  active: { background: '#333' },
  disabled: { background: '#222', color: '#666' },
};

Focus Navigation

// Enable focus navigation
ui.enableFocusNavigation();

// Navigate with keyboard/gamepad
ui.focusNext();
ui.focusPrevious();
ui.activateFocused();

Peer Dependencies

• @web-engine-dev/math - Vector math (optional)
• @web-engine-dev/events - Event system (optional)
• @web-engine-dev/input - Input handling (optional)