@willwade/aac-processors 0.0.10 → 0.0.12

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

@@ -0,0 +1,140 @@
+"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
+        const wordEffortMap = new Map();
+        metrics.buttons.forEach((btn) => {
+            const existing = wordEffortMap.get(btn.label);
+            if (!existing || btn.effort < existing) {
+                wordEffortMap.set(btn.label, 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 effort = wordEffortMap.get(word);
+            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/processors/gridset/colorUtils.d.ts

@@ -54,6 +54,24 @@ export declare function toHexColor(value: string): string | undefined;
  * @returns Darkened hex color
  */
 export declare function darkenColor(hex: string, amount: number): string;
+/**
+ * Lighten a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to lighten (0-255)
+ * @returns Lightened hex color
+ */
+export declare function lightenColor(hex: string, amount: number): string;
+/**
+ * Convert hex color to RGBA object
+ * @param hex - Hex color string (#RRGGBB or #RRGGBBAA)
+ * @returns RGBA object with r, g, b, a properties (0-1 for alpha)
+ */
+export declare function hexToRgba(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
 /**
  * Normalize any color format to Grid3's 8-digit hex format
  * @param input - Color string in any supported format

package/dist/processors/gridset/colorUtils.js

@@ -16,6 +16,8 @@ exports.clampColorChannel = clampColorChannel;
 exports.clampAlpha = clampAlpha;
 exports.toHexColor = toHexColor;
 exports.darkenColor = darkenColor;
+exports.lightenColor = lightenColor;
+exports.hexToRgba = hexToRgba;
 exports.normalizeColor = normalizeColor;
 exports.ensureAlphaChannel = ensureAlphaChannel;
 /**
@@ -288,6 +290,40 @@ function darkenColor(hex, amount) {
     const newB = clamp(b - amount);
     return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
 }
+/**
+ * Lighten a hex color by a specified amount
+ * @param hex - Hex color string
+ * @param amount - Amount to lighten (0-255)
+ * @returns Lightened hex color
+ */
+function lightenColor(hex, amount) {
+    const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+    const rgb = normalized.substring(0, 6);
+    const alpha = normalized.substring(6) || 'FF';
+    const r = parseInt(rgb.substring(0, 2), 16);
+    const g = parseInt(rgb.substring(2, 4), 16);
+    const b = parseInt(rgb.substring(4, 6), 16);
+    const clamp = (val) => Math.max(0, Math.min(255, val));
+    const newR = clamp(r + amount);
+    const newG = clamp(g + amount);
+    const newB = clamp(b + amount);
+    return `#${channelToHex(newR)}${channelToHex(newG)}${channelToHex(newB)}${alpha.toUpperCase()}`;
+}
+/**
+ * Convert hex color to RGBA object
+ * @param hex - Hex color string (#RRGGBB or #RRGGBBAA)
+ * @returns RGBA object with r, g, b, a properties (0-1 for alpha)
+ */
+function hexToRgba(hex) {
+    const normalized = ensureAlphaChannel(hex).substring(1); // strip #
+    const rgb = normalized.substring(0, 6);
+    const alphaHex = normalized.substring(6) || 'FF';
+    const r = parseInt(rgb.substring(0, 2), 16);
+    const g = parseInt(rgb.substring(2, 4), 16);
+    const b = parseInt(rgb.substring(4, 6), 16);
+    const a = parseInt(alphaHex, 16) / 255;
+    return { r, g, b, a };
+}
 /**
  * Normalize any color format to Grid3's 8-digit hex format
  * @param input - Color string in any supported format

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

@@ -0,0 +1,103 @@
+/**
+ * Grid 3 Command Definitions and Detection System
+ *
+ * This module provides comprehensive metadata for all Grid 3 commands,
+ * organized by plugin/category. It enables:
+ * - Command detection and classification
+ * - Parameter extraction
+ * - Future extensibility for command execution
+ * - Semantic action mapping
+ *
+ * Grid 3 has 33+ plugins with 200+ commands. This catalog captures
+ * the most commonly used and important commands.
+ */
+/**
+ * Command categories in Grid 3
+ */
+export declare enum Grid3CommandCategory {
+    NAVIGATION = "navigation",
+    COMMUNICATION = "communication",
+    TEXT_EDITING = "text_editing",
+    COMPUTER_CONTROL = "computer_control",
+    WEB_BROWSER = "web_browser",
+    EMAIL = "email",
+    PHONE = "phone",
+    SMS = "sms",
+    SYSTEM = "system",
+    SETTINGS = "settings",
+    SPEECH = "speech",
+    AUTO_CONTENT = "auto_content",
+    ENVIRONMENT_CONTROL = "environment_control",
+    MOUSE = "mouse",
+    WINDOW = "window",
+    MEDIA = "media",
+    CUSTOM = "custom"
+}
+/**
+ * Parameter definition for commands
+ */
+export interface CommandParameter {
+    key: string;
+    type: 'string' | 'number' | 'boolean' | 'grid' | 'color' | 'font';
+    required: boolean;
+    description?: string;
+}
+/**
+ * Command metadata definition
+ */
+export interface Grid3CommandDefinition {
+    id: string;
+    category: Grid3CommandCategory;
+    pluginId: string;
+    displayName: string;
+    description: string;
+    parameters?: CommandParameter[];
+    platforms?: ('desktop' | 'ios' | 'medicare' | 'medicareBionics')[];
+    deprecated?: boolean;
+}
+/**
+ * Registry of all Grid 3 commands
+ * Key is command ID (e.g., 'Jump.To', 'Action.InsertText')
+ */
+export declare const GRID3_COMMANDS: Record<string, Grid3CommandDefinition>;
+/**
+ * Get command definition by ID
+ */
+export declare function getCommandDefinition(commandId: string): Grid3CommandDefinition | undefined;
+/**
+ * Check if a command ID is known
+ */
+export declare function isKnownCommand(commandId: string): boolean;
+/**
+ * Get all commands for a specific plugin
+ */
+export declare function getCommandsByPlugin(pluginId: string): Grid3CommandDefinition[];
+/**
+ * Get all commands in a category
+ */
+export declare function getCommandsByCategory(category: Grid3CommandCategory): Grid3CommandDefinition[];
+/**
+ * Get all command IDs
+ */
+export declare function getAllCommandIds(): string[];
+/**
+ * Get all plugin IDs that have commands
+ */
+export declare function getAllPluginIds(): string[];
+/**
+ * Extract parameters from a Grid 3 command object
+ */
+export interface ExtractedParameters {
+    [key: string]: string | number | boolean;
+}
+export declare function extractCommandParameters(command: any): ExtractedParameters;
+/**
+ * Detect and categorize a command from Grid 3
+ */
+export declare function detectCommand(commandObj: any): {
+    id: string;
+    definition?: Grid3CommandDefinition;
+    parameters: ExtractedParameters;
+    category: Grid3CommandCategory | 'unknown';
+    pluginId: string | 'unknown';
+};