@willwade/aac-processors 0.0.4 → 0.0.6

package/dist/processors/snapProcessor.js

@@ -185,7 +185,6 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                     }
                     // Create semantic action for Snap button
                     let semanticAction;
-                    let legacyAction = null;
                     if (targetPageUniqueId) {
                         semanticAction = {
                             category: treeStructure_1.AACSemanticCategory.NAVIGATION,
@@ -202,10 +201,6 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
                                 targetPageId: targetPageUniqueId,
                             },
                         };
-                        legacyAction = {
-                            type: 'NAVIGATE',
-                            targetPageId: targetPageUniqueId,
-                        };
                     }
                     else {
                         semanticAction = {
@@ -283,15 +278,16 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
             return tree;
         }
         catch (error) {
+            const fileIdentifier = typeof filePathOrBuffer === 'string' ? filePathOrBuffer : '[buffer input]';
             // Provide more specific error messages
             if (error.code === 'SQLITE_NOTADB') {
                 throw new Error(`Invalid SQLite database file: ${typeof filePathOrBuffer === 'string' ? filePathOrBuffer : 'buffer'}`);
             }
             else if (error.code === 'ENOENT') {
-                throw new Error(`File not found: ${filePathOrBuffer}`);
+                throw new Error(`File not found: ${fileIdentifier}`);
             }
             else if (error.code === 'EACCES') {
-                throw new Error(`Permission denied accessing file: ${filePathOrBuffer}`);
+                throw new Error(`Permission denied accessing file: ${fileIdentifier}`);
             }
             else {
                 throw new Error(`Failed to load Snap file: ${error.message}`);
@@ -320,15 +316,24 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
         Object.values(tree.pages).forEach((page) => {
             // Translate page names
             if (page.name && translations.has(page.name)) {
-                page.name = translations.get(page.name);
+                const translatedName = translations.get(page.name);
+                if (translatedName !== undefined) {
+                    page.name = translatedName;
+                }
             }
             // Translate button labels and messages
             page.buttons.forEach((button) => {
                 if (button.label && translations.has(button.label)) {
-                    button.label = translations.get(button.label);
+                    const translatedLabel = translations.get(button.label);
+                    if (translatedLabel !== undefined) {
+                        button.label = translatedLabel;
+                    }
                 }
                 if (button.message && translations.has(button.message)) {
-                    button.message = translations.get(button.message);
+                    const translatedMessage = translations.get(button.message);
+                    if (translatedMessage !== undefined) {
+                        button.message = translatedMessage;
+                    }
                 }
             });
         });
@@ -419,6 +424,9 @@ class SnapProcessor extends baseProcessor_1.BaseProcessor {
             // Second pass: create buttons with proper page references
             Object.values(tree.pages).forEach((page) => {
                 const numericPageId = pageIdMap.get(page.id);
+                if (numericPageId === undefined) {
+                    return;
+                }
                 page.buttons.forEach((button, index) => {
                     // Find button position in grid layout
                     let gridPosition = `${index % 4},${Math.floor(index / 4)}`; // Default fallback

package/dist/processors/touchchatProcessor.js

@@ -12,6 +12,9 @@ const better_sqlite3_1 = __importDefault(require("better-sqlite3"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
+const toNumberOrUndefined = (value) => typeof value === 'number' ? value : undefined;
+const toStringOrUndefined = (value) => typeof value === 'string' && value.length > 0 ? value : undefined;
+const toBooleanOrUndefined = (value) => typeof value === 'number' ? value !== 0 : undefined;
 function intToHex(colorInt) {
     if (colorInt === null || typeof colorInt === 'undefined') {
         return undefined;
@@ -84,7 +87,9 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
             const buttonStyles = new Map();
             const pageStyles = new Map();
             try {
-                const buttonStyleRows = db.prepare('SELECT * FROM button_styles').all();
+                const buttonStyleRows = db
+                    .prepare('SELECT * FROM button_styles')
+                    .all();
                 buttonStyleRows.forEach((style) => {
                     buttonStyles.set(style.id, style);
                 });
@@ -162,15 +167,15 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                         style: {
                             backgroundColor: intToHex(style?.body_color),
                             borderColor: intToHex(style?.border_color),
-                            borderWidth: style?.border_width,
+                            borderWidth: toNumberOrUndefined(style?.border_width),
                             fontColor: intToHex(style?.font_color),
-                            fontSize: style?.font_height,
-                            fontFamily: style?.font_name,
-                            fontWeight: style?.font_bold ? 'bold' : 'normal',
-                            fontStyle: style?.font_italic ? 'italic' : 'normal',
-                            textUnderline: style?.font_underline,
-                            transparent: style?.transparent,
-                            labelOnTop: style?.label_on_top,
+                            fontSize: toNumberOrUndefined(style?.font_height),
+                            fontFamily: toStringOrUndefined(style?.font_name),
+                            fontWeight: style?.font_bold ? 'bold' : undefined,
+                            fontStyle: style?.font_italic ? 'italic' : undefined,
+                            textUnderline: toBooleanOrUndefined(style?.font_underline),
+                            transparent: toBooleanOrUndefined(style?.transparent),
+                            labelOnTop: toBooleanOrUndefined(style?.label_on_top),
                         },
                     });
                     buttonBoxes.get(cell.box_id)?.push({
@@ -276,15 +281,15 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                         style: {
                             backgroundColor: intToHex(style?.body_color),
                             borderColor: intToHex(style?.border_color),
-                            borderWidth: style?.border_width,
+                            borderWidth: toNumberOrUndefined(style?.border_width),
                             fontColor: intToHex(style?.font_color),
-                            fontSize: style?.font_height,
-                            fontFamily: style?.font_name,
-                            fontWeight: style?.font_bold ? 'bold' : 'normal',
-                            fontStyle: style?.font_italic ? 'italic' : 'normal',
-                            textUnderline: style?.font_underline,
-                            transparent: style?.transparent,
-                            labelOnTop: style?.label_on_top,
+                            fontSize: toNumberOrUndefined(style?.font_height),
+                            fontFamily: toStringOrUndefined(style?.font_name),
+                            fontWeight: style?.font_bold ? 'bold' : undefined,
+                            fontStyle: style?.font_italic ? 'italic' : undefined,
+                            textUnderline: toBooleanOrUndefined(style?.font_underline),
+                            transparent: toBooleanOrUndefined(style?.transparent),
+                            labelOnTop: toBooleanOrUndefined(style?.label_on_top),
                         },
                     });
                     // Find the page that references this resource
@@ -380,15 +385,24 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
         Object.values(tree.pages).forEach((page) => {
             // Translate page names
             if (page.name && translations.has(page.name)) {
-                page.name = translations.get(page.name);
+                const translatedName = translations.get(page.name);
+                if (translatedName !== undefined) {
+                    page.name = translatedName;
+                }
             }
             // Translate button labels and messages
             page.buttons.forEach((button) => {
                 if (button.label && translations.has(button.label)) {
-                    button.label = translations.get(button.label);
+                    const translatedLabel = translations.get(button.label);
+                    if (translatedLabel !== undefined) {
+                        button.label = translatedLabel;
+                    }
                 }
                 if (button.message && translations.has(button.message)) {
-                    button.message = translations.get(button.message);
+                    const translatedMessage = translations.get(button.message);
+                    if (translatedMessage !== undefined) {
+                        button.message = translatedMessage;
+                    }
                 }
             });
         });
@@ -560,7 +574,10 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                         insertPageStyle.run(pageStyleId, hexToInt(page.style.backgroundColor), page.style.backgroundColor ? 1 : 0);
                     }
                     else {
-                        pageStyleId = pageStyleMap.get(styleKey);
+                        const existingPageStyleId = pageStyleMap.get(styleKey);
+                        if (typeof existingPageStyleId === 'number') {
+                            pageStyleId = existingPageStyleId;
+                        }
                     }
                 }
                 // Insert resource for page name
@@ -577,6 +594,9 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
             // Second pass: create buttons and their relationships
             Object.values(tree.pages).forEach((page) => {
                 const numericPageId = pageIdMap.get(page.id);
+                if (numericPageId === undefined) {
+                    return;
+                }
                 if (page.buttons.length > 0) {
                     // Calculate grid dimensions from page.grid or use fallback
                     let gridWidth = 4; // Default fallback
@@ -631,7 +651,10 @@ class TouchChatProcessor extends baseProcessor_1.BaseProcessor {
                                 insertButtonStyle.run(buttonStyleId, button.style.labelOnTop ? 1 : 0, button.style.transparent ? 1 : 0, hexToInt(button.style.fontColor), hexToInt(button.style.backgroundColor), hexToInt(button.style.borderColor), button.style.borderWidth, button.style.fontFamily, button.style.fontWeight === 'bold' ? 1 : 0, button.style.textUnderline ? 1 : 0, button.style.fontStyle === 'italic' ? 1 : 0, button.style.fontSize);
                             }
                             else {
-                                buttonStyleId = buttonStyleMap.get(styleKey);
+                                const existingButtonStyleId = buttonStyleMap.get(styleKey);
+                                if (typeof existingButtonStyleId === 'number') {
+                                    buttonStyleId = existingButtonStyleId;
+                                }
                             }
                         }
                         if (!insertedButtonIds.has(numericButtonId)) {

package/dist/types/aac.d.ts

@@ -33,6 +33,10 @@ export interface AACPage {
     buttons: AACButton[];
     parentId: string | null;
     style?: AACStyle;
+    locale?: string;
+    descriptionHtml?: string;
+    images?: any[];
+    sounds?: any[];
 }
 export interface AACTree {
     pages: {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@willwade/aac-processors",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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",