@willwade/aac-processors 0.0.3 → 0.0.5

package/docs/Grid3-Styling-Guide.md

@@ -0,0 +1,287 @@
+# Grid3 Styling Guide
+
+This guide explains how to work with Grid3 styles using the AACProcessors library.
+
+## Overview
+
+Grid3 uses a sophisticated styling system with:
+- **Default styles** for common UI elements
+- **Category styles** for organizing content by semantic meaning
+- **Inline style overrides** for cell-specific customization
+- **Style inheritance** through `BasedOnStyle` references
+
+## Default Styles
+
+The library provides built-in default styles for common use cases:
+
+### Available Default Styles
+
+| Style Name | Purpose | Background | Text Color |
+|-----------|---------|-----------|-----------|
+| `Default` | General purpose cells | Light blue (#E2EDF8) | Black |
+| `Workspace` | Message/chat area | White (#FFFFFF) | Black |
+| `Auto content` | Wordlists, predictions | Light blue (#E8F4F8) | Black |
+| `Vocab cell` | Vocabulary cells | Light blue (#E8F4F8) | Black |
+| `Keyboard key` | On-screen keyboard | Light gray (#F0F0F0) | Black |
+
+### Category Styles
+
+Category styles are used for organizing content by semantic meaning:
+
+| Style Name | Color | Use Case |
+|-----------|-------|----------|
+| `Actions category style` | Blue (#4472C4) | Action verbs, commands |
+| `People category style` | Orange (#ED7D31) | Names, people |
+| `Places category style` | Gray (#A5A5A5) | Locations, places |
+| `Descriptive category style` | Green (#70AD47) | Adjectives, descriptors |
+| `Social category style` | Gold (#FFC000) | Social phrases, greetings |
+| `Questions category style` | Light blue (#5B9BD5) | Questions, interrogatives |
+| `Little words category style` | Brown (#C55A11) | Function words, particles |
+
+## Using Styles in Code
+
+### Import Style Helpers
+
+```typescript
+import {
+  DEFAULT_GRID3_STYLES,
+  CATEGORY_STYLES,
+  createDefaultStylesXml,
+  createCategoryStyle,
+  ensureAlphaChannel,
+} from 'aac-processors';
+```
+
+### Access Predefined Styles
+
+```typescript
+// Get a specific default style
+const defaultStyle = DEFAULT_GRID3_STYLES['Default'];
+console.log(defaultStyle.BackColour); // #E2EDF8FF
+
+// Get a category style
+const actionStyle = CATEGORY_STYLES['Actions category style'];
+console.log(actionStyle.BackColour); // #4472C4FF
+```
+
+### Create Custom Category Styles
+
+```typescript
+// Create a custom category style with automatic border darkening
+const customStyle = createCategoryStyle(
+  'My Category',
+  '#FF6B6B', // Background color
+  '#FFFFFF'  // Font color (optional, defaults to white)
+);
+
+// Result:
+// {
+//   BackColour: '#FF6B6BFF',
+//   TileColour: '#FF6B6BFF',
+//   BorderColour: '#CB5555FF', // Automatically darkened
+//   FontColour: '#FFFFFFFF',
+//   FontName: 'Arial',
+//   FontSize: '16'
+// }
+```
+
+### Generate Default Styles XML
+
+```typescript
+// Generate Settings0/styles.xml with all default and category styles
+const stylesXml = createDefaultStylesXml(true);
+
+// Or just default styles without categories
+const basicStylesXml = createDefaultStylesXml(false);
+```
+
+### Ensure Color Has Alpha Channel
+
+Grid3 requires colors in 8-digit ARGB format (#AARRGGBBFF):
+
+```typescript
+import { ensureAlphaChannel } from 'aac-processors';
+
+ensureAlphaChannel('#FF0000');      // Returns: #FF0000FF
+ensureAlphaChannel('#F00');         // Returns: #FF0000FF
+ensureAlphaChannel('#FF0000FF');    // Returns: #FF0000FF (unchanged)
+ensureAlphaChannel(undefined);      // Returns: #FFFFFFFF (white)
+```
+
+## Applying Styles to Cells
+
+### Using BasedOnStyle Reference
+
+In Grid3 XML, cells reference styles by name:
+
+```xml
+<Cell X="0" Y="0">
+  <Content>
+    <CaptionAndImage>
+      <Caption>Hello</Caption>
+    </CaptionAndImage>
+    <Style>
+      <BasedOnStyle>Actions category style</BasedOnStyle>
+    </Style>
+  </Content>
+</Cell>
+```
+
+### Inline Style Overrides
+
+You can override specific properties while keeping the base style:
+
+```xml
+<Cell X="1" Y="0">
+  <Content>
+    <CaptionAndImage>
+      <Caption>Custom</Caption>
+    </CaptionAndImage>
+    <Style>
+      <BasedOnStyle>Default</BasedOnStyle>
+      <BackColour>#FF0000FF</BackColour>  <!-- Override background -->
+      <FontSize>20</FontSize>             <!-- Override font size -->
+    </Style>
+  </Content>
+</Cell>
+```
+
+## Color Format
+
+Grid3 uses 8-digit ARGB hexadecimal format: `#AARRGGBBFF`
+
+- **AA**: Alpha channel (FF = fully opaque, 00 = fully transparent)
+- **RR**: Red component (00-FF)
+- **GG**: Green component (00-FF)
+- **BB**: Blue component (00-FF)
+- **FF**: Always FF for Grid3 (fully opaque)
+
+### Examples
+
+| Color | Hex Code | Description |
+|-------|----------|-------------|
+| White | #FFFFFFFF | Fully opaque white |
+| Black | #000000FF | Fully opaque black |
+| Red | #FF0000FF | Fully opaque red |
+| Blue | #0000FFFF | Fully opaque blue |
+| Green | #00FF00FF | Fully opaque green |
+
+## Style Inheritance
+
+Grid3 uses a cascading style system:
+
+1. **Theme** provides base properties (Modern, Kids/Bubble, Flat/Blocky, Explorer)
+2. **Built-in style** defines category defaults
+3. **Cell-specific overrides** apply on top
+
+```xml
+<!-- Example: Override just the background color -->
+<Style>
+  <BasedOnStyle>Actions category style</BasedOnStyle>
+  <BackColour>#FF0000FF</BackColour>  <!-- Override just this property -->
+</Style>
+```
+
+## Creating Gridsets with Styles
+
+### Using GridsetProcessor
+
+```typescript
+import { GridsetProcessor, AACTree, AACPage, AACButton } from 'aac-processors';
+
+const processor = new GridsetProcessor();
+const tree = new AACTree();
+
+// Create a page with styling
+const page = new AACPage({
+  id: 'main-page',
+  name: 'Main Board',
+  grid: [],
+  buttons: [],
+  parentId: null,
+  style: {
+    backgroundColor: '#f0f8ff',
+    fontFamily: 'Arial',
+    fontSize: 16,
+  },
+});
+
+// Create styled buttons
+const button = new AACButton({
+  id: 'btn-1',
+  label: 'Hello',
+  message: 'Hello, how are you?',
+  style: {
+    backgroundColor: '#4472C4',  // Blue (Actions category)
+    fontColor: '#FFFFFF',
+    fontSize: 18,
+    fontFamily: 'Arial',
+  },
+});
+
+page.addButton(button);
+tree.addPage(page);
+
+// Save with styles
+processor.saveFromTree(tree, 'output.gridset');
+```
+
+### Using Grid-Generator
+
+```typescript
+import { generateGridset } from '@willwade/grid-generator';
+
+const template = {
+  aacsystem: 'Grid3',
+  homeGrid: {
+    enabled: true,
+    name: 'Home',
+    title: 'Categories',
+  },
+  wordlists: [
+    {
+      name: 'Greetings',
+      items: ['Hello', 'Hi', 'Hey'],
+      partOfSpeech: 'Interjection',
+    },
+  ],
+};
+
+const gridset = generateGridset(template);
+```
+
+## Best Practices
+
+1. **Use category styles** for semantic organization - helps with accessibility and consistency
+2. **Maintain contrast** - ensure text color has sufficient contrast with background
+3. **Use consistent fonts** - stick to standard fonts like Arial, Verdana, or Roboto
+4. **Test in Grid3** - always verify styling in the actual Grid3 application
+5. **Document custom styles** - if creating custom category styles, document their purpose
+6. **Use inline overrides sparingly** - prefer creating new styles for significant variations
+
+## Troubleshooting
+
+### Styles Not Appearing
+
+- Verify `Settings0/styles.xml` exists in the gridset
+- Check that style names in cells match exactly (case-sensitive)
+- Ensure colors are in 8-digit ARGB format
+
+### Colors Look Wrong
+
+- Verify alpha channel is FF (fully opaque)
+- Check RGB values are correct
+- Test in Grid3 to see actual rendering
+
+### Performance Issues
+
+- Avoid creating too many unique styles (consolidate similar styles)
+- Use style references instead of inline overrides when possible
+- Keep font sizes reasonable (12-24 points typical)
+
+## See Also
+
+- [Grid3 XML Format Documentation](./Grid3-XML-Format.md)
+- [Wordlist Helpers Guide](./Grid3-Wordlist-Helpers.md)
+- [AACProcessors API Reference](./API-Reference.md)
+

package/examples/README.md

@@ -1,31 +1,43 @@
-# AAC Processors Examples
+# AAC Processors Example Pagesets
 
-This directory contains example scripts demonstrating various uses of the AAC Processors library.
+This directory contains example AAC pagesets in various formats used for testing and demonstration purposes.
 
-## Translation Demo
+## Available Pagesets
 
-Demonstrates how to translate AAC files between languages using various translation services.
+### Grid3 Format (.gridset)
+- **example.gridset** - Main example pageset with multiple grids and wordlists
+- **example-images.gridset** - Example pageset with embedded images
 
-### Setup
+### Snap Format (.spb, .sps)
+- **example.spb** - Snap pageset (binary format)
+- **example.sps** - Snap pageset (alternative format)
 
-```bash
-# Install example-specific dependencies
-cd examples
-npm install
+### TouchChat Format (.ce)
+- **example.ce** - TouchChat pageset
 
-# Set up environment variables
-export AZURE_TRANSLATOR_KEY="your-key"
-export GOOGLE_TRANSLATE_KEY="your-key"
-```
+### OBF/OBZ Format (.obf, .obz)
+- **example.obf** - OBF pageset (JSON-based)
+- **example.obz** - OBZ pageset (compressed)
 
-### Usage
+### Asterics Grid Format (.grd)
+- **example.grd** - Asterics Grid pageset
+- **example2.grd** - Alternative Asterics Grid pageset
 
-```bash
-# Basic usage
-node translate_demo.js ../path/to/input.gridset --endlang fr
+### DOT Format (.dot)
+- **example.dot** - Simple DOT format pageset
+- **communikate.dot** - Communikate DOT format pageset
 
-# With confidence checking
-node translate_demo.js ../path/to/input.gridset --endlang fr --enable-confidence-check
-```
+### OPML Format (.opml)
+- **example.opml** - OPML pageset
 
-Note: These examples are for demonstration purposes only and have their own dependencies separate from the main package.
+### Styled Output
+- **styled-output/** - Directory containing example pagesets with styling applied
+
+## Usage
+
+These pagesets are used by:
+- Unit tests in the main test suite
+- Demo scripts in the `scripts/` directory
+- Integration examples
+
+To run demo scripts that use these pagesets, see the [scripts/README.md](../scripts/README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A comprehensive TypeScript library for processing AAC (Augmentative and Alternative Communication) file formats with translation support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/examples/demo.js

@@ -1,143 +0,0 @@
-// AACProcessors Demo: Showcase all engines and features
-const path = require('path');
-
-// Import processors
-const { DotProcessor, OpmlProcessor, SnapProcessor, GridsetProcessor, TouchChatProcessor, ApplePanelsProcessor, ObfProcessor } = require('../dist/processors');
-
-// Optional: pretty printer
-let prettyPrint;
-try {
-  prettyPrint = require('../dist/viewer/prettyPrint');
-} catch {}
-
-// Optional: symbol tools
-let symbolTools;
-try {
-  symbolTools = require('../dist/optional/symbolTools');
-} catch {}
-
-// --- DotProcessor ---
-console.log('\n=== DOT Example ===');
-try {
-  const dotFile = path.join(__dirname, 'example.dot');
-  const dotProcessor = new DotProcessor();
-  const dotTree = dotProcessor.loadIntoTree(dotFile);
-  console.log('DOT tree:', dotTree);
-  console.log('DOT texts:', dotProcessor.extractTexts ? dotProcessor.extractTexts(dotFile) : '(no extractTexts)');
-  if (prettyPrint) prettyPrint.printTree(dotTree, { showNavigation: true });
-} catch (e) {
-  console.warn('DOT demo error:', e.message);
-}
-
-// --- OPMLProcessor ---
-console.log('\n=== OPML Example ===');
-try {
-  const opmlFile = path.join(__dirname, 'example.opml');
-  const opmlProcessor = new OpmlProcessor();
-  const opmlTree = opmlProcessor.loadIntoTree(opmlFile);
-  console.log('OPML tree:', opmlTree);
-  console.log('OPML texts:', opmlProcessor.extractTexts ? opmlProcessor.extractTexts(opmlFile) : '(no extractTexts)');
-  if (prettyPrint) prettyPrint.printTree(opmlTree, { showNavigation: true });
-} catch (e) {
-  console.warn('OPML demo error:', e.message);
-}
-
-
-
-// --- SnapProcessor (SPB) ---
-console.log('\n=== Snap Example (.spb) ===');
-try {
-  const spbFile = path.join(__dirname, 'example.spb');
-  const snapProcessor = new SnapProcessor();
-  const snapTree = snapProcessor.loadIntoTree(spbFile);
-  console.log('Snap tree (.spb):', snapTree);
-  console.log('Snap texts (.spb):', snapProcessor.extractTexts(spbFile));
-  if (prettyPrint) prettyPrint.printTree(snapTree, { showNavigation: true });
-} catch (e) {
-  console.warn('Snap demo error (.spb):', e.message);
-}
-
-// // --- SnapProcessor (SPS) ---
-// console.log('\n=== Snap Example (.sps) ===');
-// try {
-//   const spsFile = path.join(__dirname, 'example.sps');
-//   const snapProcessor = new SnapProcessor();
-//   const snapTree = snapProcessor.loadIntoTree(spsFile);
-//   console.log('Snap tree (.sps):', snapTree);
-//   console.log('Snap texts (.sps):', snapProcessor.extractTexts(spsFile));
-//   if (prettyPrint) prettyPrint.printTree(snapTree, { showNavigation: true });
-// } catch (e) {
-//   console.warn('Snap demo error (.sps):', e.message);
-// }
-
-// --- GridsetProcessor ---
-console.log('\n=== Gridset Example ===');
-try {
-  const gridsetFile = path.join(__dirname, 'example.gridset');
-  const gridsetProcessor = new GridsetProcessor();
-  const gridTree = gridsetProcessor.loadIntoTree(gridsetFile);
-  console.log('Gridset tree:', gridTree);
-  console.log('Gridset texts:', gridsetProcessor.extractTexts(gridsetFile));
-  if (prettyPrint) prettyPrint.printTree(gridTree, { showNavigation: true });
-} catch (e) {
-  console.warn('Gridset demo error:', e.message);
-}
-
-// --- TouchChatProcessor ---
-console.log('\n=== TouchChat Example ===');
-try {
-  const touchchatFile = path.join(__dirname, 'example.ce');
-  const touchchatProcessor = new TouchChatProcessor();
-  const tcTree = touchchatProcessor.loadIntoTree(touchchatFile);
-  console.log('TouchChat tree:', tcTree);
-  console.log('TouchChat texts:', touchchatProcessor.extractTexts(touchchatFile));
-  if (prettyPrint) prettyPrint.printTree(tcTree, { showNavigation: true });
-} catch (e) {
-  console.warn('TouchChat demo error:', e.message);
-}
-
-// --- OBF/OBZ Processor ---
-console.log('\n=== OBF/OBZ Example ===');
-try {
-  // Use ObfProcessor from dist, matching others
-const obfProcessor = new ObfProcessor();
-  const obzFile = path.join(__dirname, 'example.obz');
-  // If loadIntoTree is async, use then/catch. If not, call directly.
-  let obTree;
-  try {
-    obTree = obfProcessor.loadIntoTree(obzFile);
-    console.log('OBZ tree:', obTree);
-    // Try extractTexts if available
-    if (obfProcessor.extractTexts) {
-      try {
-        const texts = obfProcessor.extractTexts(obzFile);
-        console.log('OBZ texts:', texts);
-      } catch (e) {
-        console.warn('OBZ extractTexts error:', e.message);
-      }
-    }
-    if (prettyPrint) prettyPrint.printTree(obTree, { showNavigation: true });
-    console.log('\nDemo complete.');
-  } catch (e) {
-    console.warn('OBZ demo error:', e.message);
-    console.log('\nDemo complete.');
-  }
-  // Return here so the rest of the demo waits for async
-  return;
-} catch (e) {
-  console.warn('OBZ demo error:', e.message);
-}
-
-// --- ApplePanelsProcessor (if implemented) ---
-// console.log('\n=== Apple Panels Example ===');
-// try {
-//   const applePanelsFile = path.join(__dirname, 'example.ascconfig');
-//   const applePanelsProcessor = new ApplePanelsProcessor();
-//   const apTree = applePanelsProcessor.loadIntoTree(applePanelsFile);
-//   console.log('Apple Panels tree:', apTree);
-//   if (prettyPrint) prettyPrint.printTree(apTree, { showNavigation: true });
-// } catch (e) {
-//   console.warn('Apple Panels demo error:', e.message);
-// }
-
-console.log('\nDemo complete.');