@willwade/aac-processors 0.0.11 → 0.0.13

package/dist/optional/analytics/metrics/vocabulary.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Vocabulary Coverage Analysis
+ *
+ * Analyzes how well an AAC board set covers core vocabulary
+ * and identifies missing/extra words compared to reference lists.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VocabularyAnalyzer = void 0;
+const index_1 = require("../reference/index");
+const effort_1 = require("./effort");
+class VocabularyAnalyzer {
+    constructor(referenceLoader) {
+        this.referenceLoader = referenceLoader || new index_1.ReferenceLoader();
+    }
+    /**
+     * Analyze vocabulary coverage against core lists
+     */
+    analyze(metrics, options) {
+        // const locale = options?.locale || metrics.locale || 'en';
+        const highEffortThreshold = options?.highEffortThreshold || 5.0;
+        const lowEffortThreshold = options?.lowEffortThreshold || 2.0;
+        // Load reference data
+        const coreLists = this.referenceLoader.loadCoreLists();
+        // Create word to effort map (using lowercase keys for matching)
+        const wordEffortMap = new Map();
+        metrics.buttons.forEach((btn) => {
+            const word = btn.label.toLowerCase();
+            const existing = wordEffortMap.get(word);
+            if (!existing || btn.effort < existing) {
+                wordEffortMap.set(word, btn.effort);
+            }
+        });
+        // Analyze each core list
+        const core_coverage = {};
+        coreLists.forEach((list) => {
+            const analysis = this.analyzeCoreList(list, wordEffortMap);
+            core_coverage[list.id] = analysis;
+        });
+        // Find extra words (words not in any core list)
+        const allCoreWords = new Set();
+        coreLists.forEach((list) => {
+            list.words.forEach((word) => allCoreWords.add(word.toLowerCase()));
+        });
+        const extraWords = [];
+        wordEffortMap.forEach((effort, word) => {
+            if (!allCoreWords.has(word.toLowerCase())) {
+                extraWords.push(word);
+            }
+        });
+        extraWords.sort((a, b) => a.localeCompare(b));
+        // Find high/low effort words
+        const highEffortWords = [];
+        const lowEffortWords = [];
+        wordEffortMap.forEach((effort, word) => {
+            if (effort > highEffortThreshold) {
+                highEffortWords.push({ word, effort });
+            }
+            else if (effort < lowEffortThreshold) {
+                lowEffortWords.push({ word, effort });
+            }
+        });
+        highEffortWords.sort((a, b) => b.effort - a.effort);
+        lowEffortWords.sort((a, b) => a.effort - b.effort);
+        return {
+            core_coverage,
+            total_unique_words: wordEffortMap.size,
+            words_with_effort: wordEffortMap.size,
+            words_requiring_spelling: 0, // Calculated during sentence analysis
+            extra_words: extraWords,
+            high_effort_words: highEffortWords.slice(0, 50), // Top 50
+            low_effort_words: lowEffortWords.slice(0, 50), // Bottom 50
+        };
+    }
+    /**
+     * Analyze coverage for a single core list
+     */
+    analyzeCoreList(list, wordEffortMap) {
+        const covered = [];
+        const missing = [];
+        let totalEffort = 0;
+        list.words.forEach((word) => {
+            const lowerWord = word.toLowerCase();
+            const effort = wordEffortMap.get(lowerWord);
+            if (effort !== undefined) {
+                covered.push(word);
+                totalEffort += effort;
+            }
+            else {
+                missing.push(word);
+            }
+        });
+        const averageEffort = covered.length > 0 ? totalEffort / covered.length : 0;
+        return {
+            name: list.name,
+            total_words: list.words.length,
+            covered: covered.length,
+            missing: missing.length,
+            coverage_percent: (covered.length / list.words.length) * 100,
+            missing_words: missing,
+            average_effort: averageEffort,
+        };
+    }
+    /**
+     * Calculate coverage percentage for a specific word list
+     */
+    calculateCoverage(wordList, metrics) {
+        const wordSet = new Set(metrics.buttons.map((btn) => btn.label.toLowerCase()));
+        const covered = [];
+        const missing = [];
+        wordList.forEach((word) => {
+            if (wordSet.has(word.toLowerCase())) {
+                covered.push(word);
+            }
+            else {
+                missing.push(word);
+            }
+        });
+        return {
+            covered,
+            missing,
+            coverage_percent: (covered.length / wordList.length) * 100,
+        };
+    }
+    /**
+     * Get effort for a word, or calculate spelling effort if missing
+     */
+    getWordEffort(word, metrics) {
+        const btn = metrics.buttons.find((b) => b.label.toLowerCase() === word.toLowerCase());
+        if (btn) {
+            return btn.effort;
+        }
+        return (0, effort_1.spellingEffort)(word);
+    }
+    /**
+     * Check if a word is in the board set
+     */
+    hasWord(word, metrics) {
+        return metrics.buttons.some((b) => b.label.toLowerCase() === word.toLowerCase());
+    }
+}
+exports.VocabularyAnalyzer = VocabularyAnalyzer;

package/dist/optional/analytics/reference/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Reference Data Loader
+ *
+ * Loads reference vocabulary lists, core lists, and sentences
+ * for AAC metrics analysis.
+ */
+import { CoreList, CommonWordsData, SynonymsData } from '../metrics/types';
+export declare class ReferenceLoader {
+    private dataDir;
+    private locale;
+    constructor(dataDir?: string, locale?: string);
+    /**
+     * Load core vocabulary lists
+     */
+    loadCoreLists(): CoreList[];
+    /**
+     * Load common words with baseline effort scores
+     */
+    loadCommonWords(): CommonWordsData;
+    /**
+     * Load synonym mappings
+     */
+    loadSynonyms(): SynonymsData;
+    /**
+     * Load test sentences
+     */
+    loadSentences(): string[][];
+    /**
+     * Load fringe vocabulary
+     */
+    loadFringe(): string[];
+    /**
+     * Load base words hash map
+     */
+    loadBaseWords(): {
+        [word: string]: boolean;
+    };
+    /**
+     * Get all reference data at once
+     */
+    loadAll(): {
+        coreLists: CoreList[];
+        commonWords: CommonWordsData;
+        synonyms: SynonymsData;
+        sentences: string[][];
+        fringe: string[];
+        baseWords: {
+            [word: string]: boolean;
+        };
+    };
+}

package/dist/optional/analytics/reference/index.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Reference Data Loader
+ *
+ * Loads reference vocabulary lists, core lists, and sentences
+ * for AAC metrics analysis.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReferenceLoader = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+class ReferenceLoader {
+    constructor(dataDir = path.join(__dirname, 'data'), locale = 'en') {
+        this.dataDir = dataDir;
+        this.locale = locale;
+    }
+    /**
+     * Load core vocabulary lists
+     */
+    loadCoreLists() {
+        const filePath = path.join(this.dataDir, `core_lists.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Load common words with baseline effort scores
+     */
+    loadCommonWords() {
+        const filePath = path.join(this.dataDir, `common_words.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Load synonym mappings
+     */
+    loadSynonyms() {
+        const filePath = path.join(this.dataDir, `synonyms.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Load test sentences
+     */
+    loadSentences() {
+        const filePath = path.join(this.dataDir, `sentences.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Load fringe vocabulary
+     */
+    loadFringe() {
+        const filePath = path.join(this.dataDir, `fringe.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Load base words hash map
+     */
+    loadBaseWords() {
+        const filePath = path.join(this.dataDir, `base_words.${this.locale}.json`);
+        const content = fs.readFileSync(filePath, 'utf-8');
+        return JSON.parse(content);
+    }
+    /**
+     * Get all reference data at once
+     */
+    loadAll() {
+        return {
+            coreLists: this.loadCoreLists(),
+            commonWords: this.loadCommonWords(),
+            synonyms: this.loadSynonyms(),
+            sentences: this.loadSentences(),
+            fringe: this.loadFringe(),
+            baseWords: this.loadBaseWords(),
+        };
+    }
+}
+exports.ReferenceLoader = ReferenceLoader;

package/dist/optional/analytics/utils/idGenerator.d.ts

@@ -0,0 +1,59 @@
+/**
+ * ID Generator Utility for AAC Metrics
+ *
+ * Generates clone_id values based on grid location and button label.
+ * Clone IDs help identify buttons that appear in the same location
+ * across different boards in an AAC system.
+ */
+/**
+ * Normalize a label for use in clone_id generation
+ * Converts to lowercase, removes apostrophes, trims whitespace
+ *
+ * @param label - The button label to normalize
+ * @returns Normalized label string
+ */
+export declare function normalizeLabelForCloneId(label: string): string;
+/**
+ * Generate a clone_id based on grid location and button label
+ *
+ * Clone ID format: "{rows}x{cols}-{row}.{col}-{label_normalized}"
+ * Example: "6x4-2.3-more" for button "more" at row 2, col 3 in a 6x4 grid
+ *
+ * @param rows - Total number of rows in the grid
+ * @param cols - Total number of columns in the grid
+ * @param row - Zero-based row index of the button
+ * @param col - Zero-based column index of the button
+ * @param label - The button label
+ * @returns A clone_id string
+ */
+export declare function generateCloneId(rows: number, cols: number, row: number, col: number, label: string): string;
+/**
+ * Generate a semantic_id based on button content
+ *
+ * Semantic IDs identify buttons with the same semantic meaning across boards.
+ * This is a fallback for formats that don't have explicit semantic IDs.
+ * Based on hash of message + label
+ *
+ * @param message - The button message/vocalization
+ * @param label - The button label
+ * @returns A semantic_id string (hash-based)
+ */
+export declare function generateSemanticId(message: string, label: string): string;
+/**
+ * Extract all semantic_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique semantic_id strings
+ */
+export declare function extractSemanticIds(buttons: Array<{
+    semantic_id?: string;
+}>): string[];
+/**
+ * Extract all clone_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique clone_id strings
+ */
+export declare function extractCloneIds(buttons: Array<{
+    clone_id?: string;
+}>): string[];

package/dist/optional/analytics/utils/idGenerator.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * ID Generator Utility for AAC Metrics
+ *
+ * Generates clone_id values based on grid location and button label.
+ * Clone IDs help identify buttons that appear in the same location
+ * across different boards in an AAC system.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeLabelForCloneId = normalizeLabelForCloneId;
+exports.generateCloneId = generateCloneId;
+exports.generateSemanticId = generateSemanticId;
+exports.extractSemanticIds = extractSemanticIds;
+exports.extractCloneIds = extractCloneIds;
+/**
+ * Normalize a label for use in clone_id generation
+ * Converts to lowercase, removes apostrophes, trims whitespace
+ *
+ * @param label - The button label to normalize
+ * @returns Normalized label string
+ */
+function normalizeLabelForCloneId(label) {
+    return label
+        .toLowerCase()
+        .replace(/['']/g, '') // Remove apostrophes
+        .replace(/\s+/g, '_') // Replace spaces with underscores
+        .trim();
+}
+/**
+ * Generate a clone_id based on grid location and button label
+ *
+ * Clone ID format: "{rows}x{cols}-{row}.{col}-{label_normalized}"
+ * Example: "6x4-2.3-more" for button "more" at row 2, col 3 in a 6x4 grid
+ *
+ * @param rows - Total number of rows in the grid
+ * @param cols - Total number of columns in the grid
+ * @param row - Zero-based row index of the button
+ * @param col - Zero-based column index of the button
+ * @param label - The button label
+ * @returns A clone_id string
+ */
+function generateCloneId(rows, cols, row, col, label) {
+    const normalizedLabel = normalizeLabelForCloneId(label);
+    return `${rows}x${cols}-${row}.${col}-${normalizedLabel}`;
+}
+/**
+ * Generate a semantic_id based on button content
+ *
+ * Semantic IDs identify buttons with the same semantic meaning across boards.
+ * This is a fallback for formats that don't have explicit semantic IDs.
+ * Based on hash of message + label
+ *
+ * @param message - The button message/vocalization
+ * @param label - The button label
+ * @returns A semantic_id string (hash-based)
+ */
+function generateSemanticId(message, label) {
+    const content = `${message || ''}::${label || ''}`;
+    // Simple hash function (djb2 algorithm)
+    let hash = 5381;
+    for (let i = 0; i < content.length; i++) {
+        hash = (hash * 33) ^ content.charCodeAt(i);
+    }
+    // Convert to positive hex string
+    return `semantic_${(hash >>> 0).toString(16)}`;
+}
+/**
+ * Extract all semantic_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique semantic_id strings
+ */
+function extractSemanticIds(buttons) {
+    const ids = new Set();
+    for (const button of buttons) {
+        if (button.semantic_id) {
+            ids.add(button.semantic_id);
+        }
+    }
+    return Array.from(ids);
+}
+/**
+ * Extract all clone_ids from a page's buttons
+ *
+ * @param buttons - Array of buttons to scan
+ * @returns Array of unique clone_id strings
+ */
+function extractCloneIds(buttons) {
+    const ids = new Set();
+    for (const button of buttons) {
+        if (button.clone_id) {
+            ids.add(button.clone_id);
+        }
+    }
+    return Array.from(ids);
+}

package/dist/optional/symbolTools.js

@@ -7,7 +7,7 @@ exports.TouchChatSymbolResolver = exports.TouchChatSymbolExtractor = exports.Gri
 exports.resolveSymbol = resolveSymbol;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
-const password_1 = require("../processors/gridset/password");
+const symbols_1 = require("../processors/gridset/symbols");
 // --- Base Classes ---
 class SymbolExtractor {
 }
@@ -61,10 +61,13 @@ exports.SnapSymbolResolver = SnapSymbolResolver;
 let AdmZip = null;
 let XMLParser = null;
 try {
+    // Dynamic requires for optional dependencies
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    AdmZip = require('adm-zip');
+    const admZipModule = require('adm-zip');
     // eslint-disable-next-line @typescript-eslint/no-var-requires
-    XMLParser = require('fast-xml-parser').XMLParser;
+    const fxpModule = require('fast-xml-parser');
+    AdmZip = admZipModule;
+    XMLParser = fxpModule.XMLParser;
 }
 catch {
     AdmZip = null;
@@ -74,19 +77,13 @@ class Grid3SymbolExtractor extends SymbolExtractor {
     getSymbolReferences(filePath) {
         if (!AdmZip || !XMLParser)
             throw new Error('adm-zip or fast-xml-parser not installed');
-        const zip = new AdmZip(filePath);
-        const parser = new XMLParser();
-        const refs = new Set();
-        const entries = (0, password_1.getZipEntriesWithPassword)(zip, (0, password_1.resolveGridsetPasswordFromEnv)());
-        entries.forEach((entry) => {
-            if (entry.entryName.endsWith('.gridset') || entry.entryName.endsWith('.gridsetx')) {
-                const xmlBuffer = entry.getData();
-                // Parse to validate XML structure (future: extract refs)
-                parser.parse(xmlBuffer.toString('utf8'));
-                // TODO: Extract symbol references from Grid 3 XML structure when needed
-            }
-        });
-        return Array.from(refs);
+        // Import GridsetProcessor dynamically to avoid circular dependencies
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { GridsetProcessor } = require('../processors/gridsetProcessor');
+        const proc = new GridsetProcessor();
+        const tree = proc.loadIntoTree(filePath);
+        // Use the existing extractSymbolReferences function from gridset/symbols.ts
+        return (0, symbols_1.extractSymbolReferences)(tree);
     }
 }
 exports.Grid3SymbolExtractor = Grid3SymbolExtractor;

package/dist/processors/astericsGridProcessor.d.ts

@@ -1,5 +1,20 @@
 import { BaseProcessor, ProcessorOptions, ExtractStringsResult, TranslatedString, SourceString } from '../core/baseProcessor';
 import { AACTree } from '../core/treeStructure';
+export declare function normalizeHexColor(hexColor: string): string | null;
+export declare function adjustHexColor(hexColor: string, amount: number): string;
+export declare function getHighContrastNeutralColor(backgroundColor: string): string;
+/**
+ * Calculate relative luminance of a color using WCAG formula
+ * @param hexColor - Hex color string (e.g., "#1d90ff")
+ * @returns Relative luminance value between 0 and 1
+ */
+export declare function calculateLuminance(hexColor: string): number;
+/**
+ * Choose white or black text color based on background luminance for optimal contrast
+ * @param backgroundColor - Background color hex string
+ * @returns "#FFFFFF" for dark backgrounds, "#000000" for light backgrounds
+ */
+export declare function getContrastingTextColor(backgroundColor: string): string;
 declare class AstericsGridProcessor extends BaseProcessor {
     private loadAudio;
     constructor(options?: ProcessorOptions & {

package/dist/processors/astericsGridProcessor.js

@@ -4,6 +4,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AstericsGridProcessor = void 0;
+exports.normalizeHexColor = normalizeHexColor;
+exports.adjustHexColor = adjustHexColor;
+exports.getHighContrastNeutralColor = getHighContrastNeutralColor;
+exports.calculateLuminance = calculateLuminance;
+exports.getContrastingTextColor = getContrastingTextColor;
 const baseProcessor_1 = require("../core/baseProcessor");
 const treeStructure_1 = require("../core/treeStructure");
 const fs_1 = __importDefault(require("fs"));
@@ -535,6 +540,17 @@ function getContrastingTextColor(backgroundColor) {
     // WCAG threshold: use white text if luminance < 0.5, black otherwise
     return luminance < 0.5 ? '#FFFFFF' : '#000000';
 }
+/**
+ * Map Asterics Grid hidden value to AAC standard visibility
+ * Asterics Grid: true = hidden, false = visible
+ * Maps to: 'Hidden' | 'Visible' | undefined
+ */
+function mapAstericsVisibility(hidden) {
+    if (hidden === undefined) {
+        return undefined; // Default to visible
+    }
+    return hidden ? 'Hidden' : 'Visible';
+}
 class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
     constructor(options = {}) {
         super(options);
@@ -979,6 +995,7 @@ class AstericsGridProcessor extends baseProcessor_1.BaseProcessor {
             targetPageId: targetPageId || undefined,
             semanticAction: semanticAction,
             audioRecording: audioRecording,
+            visibility: mapAstericsVisibility(element.hidden),
             image: imageName, // Store image filename/reference
             parameters: imageData
                 ? {

package/dist/processors/gridset/helpers.d.ts

@@ -1,4 +1,4 @@
-import { AACTree } from '../../core/treeStructure';
+import { AACTree, AACSemanticCategory, AACSemanticIntent } from '../../core/treeStructure';
 /**
  * Build a map of button IDs to resolved image entry paths for a specific page.
  * Helpful when rewriting zip entry names or validating images referenced in a grid.
@@ -66,6 +66,9 @@ export interface Grid3HistoryEntry {
         timestamp: Date;
         latitude?: number | null;
         longitude?: number | null;
+        type?: 'button' | 'action' | 'utterance' | 'note' | 'other';
+        intent?: AACSemanticIntent | string;
+        category?: AACSemanticCategory;
     }>;
     rawXml?: string;
 }

package/dist/processors/gridset/helpers.js

@@ -44,6 +44,7 @@ exports.readGrid3HistoryForUser = readGrid3HistoryForUser;
 exports.readAllGrid3History = readAllGrid3History;
 const adm_zip_1 = __importDefault(require("adm-zip"));
 const fast_xml_parser_1 = require("fast-xml-parser");
+const treeStructure_1 = require("../../core/treeStructure");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
@@ -394,6 +395,9 @@ function readGrid3History(historyDbPath) {
             timestamp: (0, dotnetTicks_1.dotNetTicksToDate)(BigInt(row.TickValue ?? 0)),
             latitude: row.Latitude ?? null,
             longitude: row.Longitude ?? null,
+            type: 'utterance',
+            intent: treeStructure_1.AACSemanticIntent.SPEAK_TEXT,
+            category: treeStructure_1.AACSemanticCategory.COMMUNICATION,
         });
         events.set(phraseId, entry);
     }