@willwade/aac-processors 0.1.20 → 0.2.0

package/dist/browser/processors/gridset/styleHelpers.js

@@ -0,0 +1,205 @@
+/**
+ * Grid3 Style Helpers
+ *
+ * Utilities for creating and managing Grid3 styles, including default styles,
+ * style XML generation, and style conversion utilities.
+ */
+import { XMLBuilder } from 'fast-xml-parser';
+import { ensureAlphaChannel, darkenColor } from './colorUtils';
+/**
+ * Cell background shapes supported by Grid 3
+ * Maps to Grid 3's CellBackgroundShape enum
+ */
+export var CellBackgroundShape;
+(function (CellBackgroundShape) {
+    CellBackgroundShape[CellBackgroundShape["Rectangle"] = 0] = "Rectangle";
+    CellBackgroundShape[CellBackgroundShape["RoundedRectangle"] = 1] = "RoundedRectangle";
+    CellBackgroundShape[CellBackgroundShape["FoldedCorner"] = 2] = "FoldedCorner";
+    CellBackgroundShape[CellBackgroundShape["Octagon"] = 3] = "Octagon";
+    CellBackgroundShape[CellBackgroundShape["Folder"] = 4] = "Folder";
+    CellBackgroundShape[CellBackgroundShape["Ellipse"] = 5] = "Ellipse";
+    CellBackgroundShape[CellBackgroundShape["SpeechBubble"] = 6] = "SpeechBubble";
+    CellBackgroundShape[CellBackgroundShape["ThoughtBubble"] = 7] = "ThoughtBubble";
+    CellBackgroundShape[CellBackgroundShape["Star"] = 8] = "Star";
+    CellBackgroundShape[CellBackgroundShape["Circle"] = 9] = "Circle";
+    CellBackgroundShape[CellBackgroundShape["ColouredCorner"] = 10] = "ColouredCorner";
+})(CellBackgroundShape || (CellBackgroundShape = {}));
+/**
+ * Human-readable shape names
+ */
+export const SHAPE_NAMES = {
+    [CellBackgroundShape.Rectangle]: 'Rectangle',
+    [CellBackgroundShape.RoundedRectangle]: 'Rounded Rectangle',
+    [CellBackgroundShape.FoldedCorner]: 'Folded Corner',
+    [CellBackgroundShape.Octagon]: 'Octagon',
+    [CellBackgroundShape.Folder]: 'Folder',
+    [CellBackgroundShape.Ellipse]: 'Ellipse',
+    [CellBackgroundShape.SpeechBubble]: 'Speech Bubble',
+    [CellBackgroundShape.ThoughtBubble]: 'Thought Bubble',
+    [CellBackgroundShape.Star]: 'Star',
+    [CellBackgroundShape.Circle]: 'Circle',
+    [CellBackgroundShape.ColouredCorner]: 'Coloured Corner',
+};
+/**
+ * Default Grid3 styles for common use cases
+ * Colors are in 8-digit ARGB hex format (#AARRGGBBFF)
+ */
+export const DEFAULT_GRID3_STYLES = {
+    Default: {
+        BackColour: '#E2EDF8FF',
+        TileColour: '#FFFFFFFF',
+        BorderColour: '#000000FF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    Workspace: {
+        BackColour: '#FFFFFFFF',
+        TileColour: '#FFFFFFFF',
+        BorderColour: '#CCCCCCFF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '14',
+    },
+    'Auto content': {
+        BackColour: '#E8F4F8FF',
+        TileColour: '#E8F4F8FF',
+        BorderColour: '#2C82C9FF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '14',
+    },
+    'Vocab cell': {
+        BackColour: '#E8F4F8FF',
+        TileColour: '#E8F4F8FF',
+        BorderColour: '#2C82C9FF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '14',
+    },
+    'Keyboard key': {
+        BackColour: '#F0F0F0FF',
+        TileColour: '#F0F0F0FF',
+        BorderColour: '#808080FF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '12',
+    },
+};
+/**
+ * Category-specific styles for navigation and organization
+ */
+export const CATEGORY_STYLES = {
+    'Actions category style': {
+        BackColour: '#4472C4FF',
+        TileColour: '#4472C4FF',
+        BorderColour: '#2F5496FF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'People category style': {
+        BackColour: '#ED7D31FF',
+        TileColour: '#ED7D31FF',
+        BorderColour: '#C65911FF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'Places category style': {
+        BackColour: '#A5A5A5FF',
+        TileColour: '#A5A5A5FF',
+        BorderColour: '#595959FF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'Descriptive category style': {
+        BackColour: '#70AD47FF',
+        TileColour: '#70AD47FF',
+        BorderColour: '#4F7C2FFF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'Social category style': {
+        BackColour: '#FFC000FF',
+        TileColour: '#FFC000FF',
+        BorderColour: '#BF8F00FF',
+        FontColour: '#000000FF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'Questions category style': {
+        BackColour: '#5B9BD5FF',
+        TileColour: '#5B9BD5FF',
+        BorderColour: '#2E5C8AFF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+    'Little words category style': {
+        BackColour: '#C55A11FF',
+        TileColour: '#C55A11FF',
+        BorderColour: '#8B3F0AFF',
+        FontColour: '#FFFFFFFF',
+        FontName: 'Arial',
+        FontSize: '16',
+    },
+};
+/**
+ * Re-export ensureAlphaChannel from colorUtils for backward compatibility
+ * @deprecated Use ensureAlphaChannel from colorUtils instead
+ */
+export { ensureAlphaChannel } from './colorUtils';
+/**
+ * Create a Grid3 style XML string with default and category styles
+ * @param includeCategories - Whether to include category-specific styles (default: true)
+ * @returns XML string for Settings0/styles.xml
+ */
+export function createDefaultStylesXml(includeCategories = true) {
+    const builder = new XMLBuilder({
+        ignoreAttributes: false,
+        format: true,
+        indentBy: '  ',
+    });
+    const styles = { ...DEFAULT_GRID3_STYLES };
+    if (includeCategories) {
+        Object.assign(styles, CATEGORY_STYLES);
+    }
+    const styleArray = Object.entries(styles).map(([key, style]) => ({
+        '@_Key': key,
+        BackColour: style.BackColour,
+        TileColour: style.TileColour,
+        BorderColour: style.BorderColour,
+        FontColour: style.FontColour,
+        FontName: style.FontName,
+        FontSize: style.FontSize?.toString(),
+    }));
+    const stylesData = {
+        StyleData: {
+            '@_xmlns:xsi': 'http://www.w3.org/2001/XMLSchema-instance',
+            Styles: {
+                Style: styleArray,
+            },
+        },
+    };
+    return builder.build(stylesData);
+}
+/**
+ * Create a custom category style
+ * @param categoryName - Name of the category
+ * @param backgroundColor - Background color in hex format
+ * @param fontColor - Font color in hex format (default: white)
+ * @returns Grid3Style object
+ */
+export function createCategoryStyle(categoryName, backgroundColor, fontColor = '#FFFFFFFF') {
+    return {
+        BackColour: ensureAlphaChannel(backgroundColor),
+        TileColour: ensureAlphaChannel(backgroundColor),
+        BorderColour: ensureAlphaChannel(darkenColor(backgroundColor, 30)),
+        FontColour: ensureAlphaChannel(fontColor),
+        FontName: 'Arial',
+        FontSize: '16',
+    };
+}

package/dist/browser/processors/gridset/symbolExtractor.js

@@ -0,0 +1,331 @@
+/**
+ * Grid 3 Symbol Extraction Strategy
+ *
+ * For converting Grid 3 gridsets to other formats (like Asterics),
+ * we need to handle symbol library references properly.
+ *
+ * Strategy:
+ * 1. Check if image is embedded in gridset (extract directly)
+ * 2. If symbol library reference:
+ *    a. Check if we can extract from .pix file (limited support)
+ *    b. Provide reference/URL for manual resolution
+ *    c. For Tawasol: provide alternative sources
+ */
+import { resolveSymbolReference, parseSymbolReference } from './symbols';
+import { defaultFileAdapter } from '../../utils/io';
+import { getZipAdapter } from '../../utils/zip';
+/**
+ * Known open-license symbol sources
+ */
+const OPEN_LICENSE_SYMBOLS = {
+    tawasl: {
+        name: 'Tawasol',
+        attribution: 'Tawasol symbols by Mada (Qatar Assistive Technology Center)',
+        license: 'CC BY-SA 4.0',
+        url: 'https://mada.org.qa/en/resources/tawasol-symbols',
+        alternativeSources: ['https://github.com/mada-qatar/Tawasol'],
+    },
+    blissx: {
+        name: 'Blissymbols',
+        attribution: 'Blissymbolics Communication International',
+        license: 'CC BY-ND 3.0',
+        url: 'https://blissymbolics.org',
+    },
+    symoji: {
+        name: 'Symoji',
+        attribution: 'Smartbox Assistive Technology',
+        license: 'Proprietary - Free use in Grid 3',
+    },
+};
+/**
+ * Extract image data for a button
+ * @param gridsetBuffer - Gridset ZIP buffer
+ * @param resolvedImageEntry - Path to embedded image in gridset
+ * @param symbolReference - Symbol library reference
+ * @param options - Extraction options
+ * @returns Extracted image data
+ */
+export async function extractButtonImage(gridsetBuffer, resolvedImageEntry, symbolReference, options = {}, fileAdapter = defaultFileAdapter, zipAdapter) {
+    // Priority 1: Use embedded image if available
+    if (resolvedImageEntry && options.preferEmbedded !== false) {
+        try {
+            const zip = zipAdapter
+                ? await zipAdapter(gridsetBuffer)
+                : await getZipAdapter(gridsetBuffer, fileAdapter);
+            const entries = zip.listFiles();
+            const entry = entries.find((e) => e === resolvedImageEntry);
+            if (entry) {
+                const data = Buffer.from(await zip.readFile(entry));
+                const format = detectImageFormat(data);
+                return {
+                    found: true,
+                    data,
+                    format,
+                    source: 'embedded',
+                    reference: resolvedImageEntry,
+                };
+            }
+        }
+        catch (error) {
+            console.warn(`Failed to extract embedded image: ${String(error)}`);
+        }
+    }
+    // Priority 2: Check symbol library reference
+    if (symbolReference) {
+        return await extractSymbolLibraryImage(symbolReference, options);
+    }
+    // Not found
+    return {
+        found: false,
+        source: 'not-found',
+    };
+}
+/**
+ * Extract image from symbol library
+ * @param reference - Symbol reference like "[tawasl]/food/apple.png"
+ * @param options - Extraction options
+ * @returns Extracted image or reference info
+ */
+export async function extractSymbolLibraryImage(reference, options = {}) {
+    const ref = parseSymbolReferenceSafe(reference);
+    if (!ref || !ref.isValid) {
+        return {
+            found: false,
+            source: 'not-found',
+            reference,
+        };
+    }
+    // Get library metadata
+    const libInfo = OPEN_LICENSE_SYMBOLS[ref.library];
+    // Resolve symbol reference and extract from .symbols file
+    const resolved = await resolveSymbolReference(reference, {
+        grid3Path: options.grid3Path,
+    });
+    const metadata = {
+        library: ref.library,
+        symbolPath: ref.path,
+        attribution: libInfo?.attribution,
+        license: libInfo?.license,
+    };
+    if (!resolved.found) {
+        // Symbol not found in library
+        if (options.onMissingSymbol) {
+            options.onMissingSymbol(ref);
+        }
+        return {
+            found: false,
+            source: 'symbol-library',
+            reference: reference,
+            metadata,
+            error: resolved.error,
+        };
+    }
+    // Successfully extracted!
+    const data = resolved.data;
+    const format = data ? detectImageFormat(data) : 'unknown';
+    return {
+        found: true,
+        data,
+        format,
+        source: 'symbol-library',
+        reference: reference,
+        metadata,
+    };
+}
+/**
+ * Convert extracted image to Asterics Grid format
+ * @param extracted - Extracted image
+ * @returns GridImage object for Asterics
+ */
+export function convertToAstericsImage(extracted) {
+    const image = {};
+    if (extracted.found && extracted.data) {
+        // Embed as base64
+        image.data = Buffer.from(extracted.data).toString('base64');
+    }
+    // Even if embedded, add attribution for symbol libraries
+    if (extracted.source === 'symbol-library') {
+        if (extracted.metadata?.attribution) {
+            image.author = extracted.metadata.attribution;
+        }
+        if (extracted.metadata?.license) {
+            image.searchProviderName = extracted.metadata.license;
+        }
+    }
+    // If not found but we have a reference, keep it for manual handling
+    if (!extracted.found && extracted.reference) {
+        image.url = `symbol:${extracted.reference}`;
+        if (extracted.metadata?.attribution) {
+            image.author = extracted.metadata.attribution;
+        }
+    }
+    return image;
+}
+/**
+ * Analyze symbol usage for a gridset
+ * @param tree - AAC tree
+ * @returns Symbol usage report
+ */
+export function analyzeSymbolExtraction(tree) {
+    const report = {
+        total: 0,
+        embedded: 0,
+        symbolLibraries: 0,
+        notFound: 0,
+        byLibrary: {},
+        missingSymbols: [],
+    };
+    for (const pageId in tree.pages) {
+        const page = tree.pages[pageId];
+        if (page.buttons) {
+            for (const button of page.buttons) {
+                report.total++;
+                // Embedded image
+                if (button.resolvedImageEntry && !button.symbolLibrary) {
+                    report.embedded++;
+                    continue;
+                }
+                // Symbol library reference
+                if (button.symbolLibrary) {
+                    report.symbolLibraries++;
+                    report.byLibrary[button.symbolLibrary] =
+                        (report.byLibrary[button.symbolLibrary] || 0) + 1;
+                    const ref = `[${button.symbolLibrary}]${button.symbolPath || ''}`;
+                    const libInfo = OPEN_LICENSE_SYMBOLS[button.symbolLibrary];
+                    report.missingSymbols.push({
+                        reference: ref,
+                        library: button.symbolLibrary,
+                        path: button.symbolPath || '',
+                        attribution: libInfo?.attribution,
+                        license: libInfo?.license,
+                    });
+                    continue;
+                }
+                // Not found
+                if (!button.resolvedImageEntry && !button.symbolLibrary) {
+                    report.notFound++;
+                }
+            }
+        }
+    }
+    return report;
+}
+/**
+ * Suggest extraction strategy based on report
+ */
+export function suggestExtractionStrategy(report) {
+    const suggestions = [];
+    if (report.embedded > 0) {
+        suggestions.push(`✓ Can extract ${report.embedded} embedded images directly`);
+    }
+    if (report.symbolLibraries > 0) {
+        suggestions.push(`⚠ ${report.symbolLibraries} symbol library references found:`);
+        Object.entries(report.byLibrary).forEach(([lib, count]) => {
+            const libInfo = OPEN_LICENSE_SYMBOLS[lib];
+            if (libInfo) {
+                suggestions.push(`  - ${lib}: ${count} symbols (${libInfo.license})`);
+                if (libInfo.alternativeSources) {
+                    suggestions.push(`    Alternative: ${libInfo.alternativeSources.join(', ')}`);
+                }
+            }
+            else {
+                suggestions.push(`  - ${lib}: ${count} symbols (Proprietary - requires Grid 3)`);
+            }
+        });
+    }
+    if (report.notFound > 0) {
+        suggestions.push(`✗ ${report.notFound} images not found`);
+    }
+    return suggestions.join('\n');
+}
+/**
+ * Detect image format from buffer
+ */
+function detectImageFormat(buffer) {
+    if (buffer.length < 4)
+        return 'unknown';
+    // PNG: 89 50 4E 47
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return 'png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return 'jpg';
+    }
+    // GIF: 47 49 46 38
+    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+        return 'gif';
+    }
+    // SVG (check for <svg text)
+    const header = buffer.slice(0, Math.min(100, buffer.length)).toString('ascii').toLowerCase();
+    if (header.includes('<svg')) {
+        return 'svg';
+    }
+    return 'unknown';
+}
+/**
+ * Safe parse of symbol reference
+ */
+function parseSymbolReferenceSafe(reference) {
+    try {
+        return parseSymbolReference(reference);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Export symbol references to CSV for manual extraction
+ */
+export async function exportSymbolReferencesToCsv(report, outputPath, fileAdapter = defaultFileAdapter) {
+    const { writeTextToPath } = fileAdapter;
+    const lines = ['Reference,Library,Path,Attribution,License'];
+    for (const symbol of report.missingSymbols) {
+        lines.push(`"${symbol.reference}","${symbol.library}","${symbol.path}","${symbol.attribution || ''}","${symbol.license || ''}"`);
+    }
+    await writeTextToPath(outputPath, lines.join('\n'));
+}
+export function createSymbolManifest(tree, gridsetName) {
+    const manifest = {
+        generatedAt: new Date().toISOString(),
+        gridset: gridsetName,
+        totalSymbols: 0,
+        embedded: 0,
+        fromLibraries: 0,
+        libraries: {},
+        symbols: [],
+    };
+    for (const pageId in tree.pages) {
+        const page = tree.pages[pageId];
+        if (page.buttons) {
+            for (const button of page.buttons) {
+                manifest.totalSymbols++;
+                if (button.resolvedImageEntry && !button.symbolLibrary) {
+                    manifest.embedded++;
+                    continue;
+                }
+                if (button.symbolLibrary) {
+                    manifest.fromLibraries++;
+                    if (!manifest.libraries[button.symbolLibrary]) {
+                        const libInfo = OPEN_LICENSE_SYMBOLS[button.symbolLibrary];
+                        manifest.libraries[button.symbolLibrary] = {
+                            count: 0,
+                            attribution: libInfo?.attribution,
+                            license: libInfo?.license,
+                            url: libInfo?.url,
+                        };
+                    }
+                    manifest.libraries[button.symbolLibrary].count++;
+                    const ref = `[${button.symbolLibrary}]${button.symbolPath || ''}`;
+                    manifest.symbols.push({
+                        pageId,
+                        buttonId: button.id,
+                        reference: ref,
+                        label: button.label,
+                    });
+                }
+            }
+        }
+    }
+    return manifest;
+}