https://github.com/willwade/aac-board-viewer
A component to preview any AAC system
https://github.com/willwade/aac-board-viewer
Last synced: 5 months ago
JSON representation
A component to preview any AAC system
- Host: GitHub
- URL: https://github.com/willwade/aac-board-viewer
- Owner: willwade
- License: mit
- Created: 2026-01-05T13:31:19.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-09T00:02:43.000Z (5 months ago)
- Last Synced: 2026-01-13T21:19:58.401Z (5 months ago)
- Language: TypeScript
- Size: 966 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# AAC Board Viewer
Universal AAC (Augmentative and Alternative Communication) board viewer component for React. Display and interact with communication boards from multiple AAC systems.
## Supported Formats
- **Grid 3** (`.gridset` files)
- **TouchChat** (`.ce` files)
- **TD Snap** (`.sps`, `.spb` files)
- **OpenBoard** (`.obf`, `.obz` files)
- **Asterics Grid** (`.grd` files)
- **Apple Panels** (`.plist` files)
- **OPML** (`.opml` files)
- **Excel** (`.xlsx` boards)
- **DOT files** (`.dot` visualizations)
Note: In-browser loading of SQLite-backed formats (`.sps`, `.spb`, `.ce`) requires SQL.js configuration.
## Features
- 🎯 **Universal Support** - Works with all major AAC file formats
- 📱 **Responsive Design** - Mobile-friendly with touch support
- 🎨 **Preserves Styling** - Maintains original colors, fonts, and layouts
- 🔗 **Interactive Navigation** - Click buttons to navigate between pages
- 🗣️ **Sentence Building** - Tap buttons to build sentences
- 🔧 **Customizable** - Flexible styling and behavior options (toggle message bar, link indicators, effort badges)
- 🌙 **Dark-mode Friendly** - Inherits host app theme when a parent adds the `dark` class
## Installation
Requires Node 20+.
```bash
npm install aac-board-viewer
```
Or with yarn:
```bash
yarn add aac-board-viewer
```
## Quick Start
### Browser Usage
SQLite-backed formats (Snap `.sps`/`.spb` and TouchChat `.ce`) require SQL.js to be configured in your bundler before loading files:
```tsx
import { configureBrowserSqlJs, loadAACFile, BoardViewer } from 'aac-board-viewer';
import sqlWasmUrl from 'sql.js/dist/sql-wasm.wasm?url';
import 'aac-board-viewer/styles';
configureBrowserSqlJs({
locateFile: () => sqlWasmUrl,
});
function MyViewer({ file }: { file: File }) {
const [tree, setTree] = useState(null);
useEffect(() => {
async function load() {
const loadedTree = await loadAACFile(file);
setTree(loadedTree);
}
load();
}, [file]);
if (!tree) return
Loading...;
return ;
}
```
### Server-Side / API Usage
```tsx
import { BoardViewer } from 'aac-board-viewer';
import 'aac-board-viewer/styles';
function MyViewer({ treeData }) {
return (
);
}
```
### Client/Server Split (Lightweight Frontend)
Parse boards on the server and send the `AACTree` JSON to the browser for rendering. This keeps the frontend lightweight while the backend handles heavy formats.
Server (Node/Express):
```ts
import express from 'express';
import { loadAACFile } from 'aac-board-viewer';
const app = express();
app.get('/api/boards/:id', async (req, res) => {
const tree = await loadAACFile(`/data/boards/${req.params.id}.sps`);
res.json(tree);
});
```
Client (React):
```tsx
import { BoardViewer } from 'aac-board-viewer';
import 'aac-board-viewer/styles';
function RemoteBoard({ id }: { id: string }) {
const [tree, setTree] = useState(null);
useEffect(() => {
fetch(`/api/boards/${id}`)
.then((res) => res.json())
.then(setTree);
}, [id]);
if (!tree) return
Loading...;
return ;
}
```
### With Metrics
```tsx
import { BoardViewer, loadAACFile, calculateMetrics } from 'aac-board-viewer';
function MetricsViewer({ filePath }) {
const [tree, setTree] = useState(null);
const [metrics, setMetrics] = useState(null);
useEffect(() => {
async function load() {
const loadedTree = await loadAACFile(filePath);
const calculatedMetrics = await calculateMetrics(loadedTree);
setTree(loadedTree);
setMetrics(calculatedMetrics);
}
load();
}, [filePath]);
if (!tree) return
Loading...;
return (
);
}
```
## Props
### BoardViewer
```typescript
interface BoardViewerProps {
tree: AACTree;
buttonMetrics?: ButtonMetric[] | null;
showMessageBar?: boolean;
showEffortBadges?: boolean;
showLinkIndicators?: boolean;
onButtonClick?: (button: AACButton) => void;
onPageChange?: (pageId: string) => void;
className?: string;
}
```
### AACTree
```typescript
interface AACTree {
pages: { [key: string]: AACPage };
rootId?: string;
toolbarId?: string;
metadata?: {
format?: string;
name?: string;
description?: string;
[key: string]: any;
};
}
```
## Advanced Usage
### Custom Styling
```tsx
```
### Event Handling
```tsx
{
console.log('Button clicked:', button.label);
// Track analytics, play sound, etc.
}}
onPageChange={(pageId) => {
console.log('Page changed to:', pageId);
// Track navigation
}}
/>
```
### Hide Message Bar
```tsx
```
## File Loading
The library provides utilities for loading AAC files:
### Programmatic Loading
```tsx
import { loadAACFile } from 'aac-board-viewer';
const tree = await loadAACFile('/path/to/file.gridset');
```
### From File Input
```tsx
import { loadAACFileFromFile } from 'aac-board-viewer';
function FileInput() {
const handleChange = async (e) => {
const file = e.target.files[0];
const tree = await loadAACFileFromFile(file);
// Use tree...
};
return ;
}
```
## Metrics Calculation
Calculate cognitive effort metrics for buttons:
```tsx
import { calculateMetrics } from 'aac-board-viewer';
const metrics = await calculateMetrics(tree, {
accessMethod: 'direct', // or 'scanning'
scanningConfig: {
pattern: 'row-column', // 'linear', 'row-column', 'block'
selectionMethod: 'auto-1-switch',
errorCorrection: false,
},
});
// metrics is an array of ButtonMetric objects:
// [{ id, label, effort, count, is_word, level }, ...]
```
## Format-Specific Notes
### Apple Panels
Apple Panels use free-form positioning. The viewer automatically:
- Converts absolute positioning to grid layout
- Calculates appropriate grid dimensions
- Preserves original button placement
### Asterics Grid
Asterics files (`.grd`) are automatically detected and processed using the Asterics Grid processor.
### GridSet / SNAP / TouchChat
These formats use native grid layouts and are displayed as-is, preserving:
- Grid dimensions (rows × columns)
- Button colors and borders
- Font sizes and styles
- Navigation links between pages
## Development
```bash
# Install dependencies
npm install
# Run demo app
npm run dev
# Build library
npm run build
# Type check
npm run type-check
# Lint
npm run lint
```
## Examples
See the `/demo` directory for complete examples:
- Basic viewer
- With metrics
- Multiple formats
- Server-side rendering
## Contributing
Contributions are welcome! Please read our contributing guidelines before submitting PRs.
## License
MIT License - see LICENSE file for details.
## Related Packages
- [@willwade/aac-processors](https://github.com/willwade/AACProcessors-nodejs) - Core AAC file processing library
## Support
- Issues: [GitHub Issues](https://github.com/willwade/aac-board-viewer/issues)
- Documentation: [Full Docs](https://github.com/willwade/aac-board-viewer/wiki)