Initial

app/js/encoding_helper.js

@@ -0,0 +1,451 @@
+/**
+ * Product Encoding/Decoding Helper
+ * 
+ * Provides functions to encode and decode product configurations into compact
+ * hex-based URL strings. Uses bit-packing for efficient, stable encoding.
+ * 
+ * Format: v-T-C-M-HHHH-HHHH-HHHH
+ * See /planning/ENCODING_SYSTEM.md for detailed documentation
+ */
+
+// ============================================================================
+// LOOKUP TABLES
+// ============================================================================
+
+const ENCODING_VERSION = 0;
+
+// Main Product Attributes (single hex character, 0-15)
+const PRODUCT_TYPE = {
+    'PATIO_DOOR': 1,
+    'STORM_DOOR': 3,
+    'STORM_WINDOW': 5,
+    'PRIMARY_WINDOW': 7
+};
+
+const PRODUCT_TYPE_REVERSE = {
+    1: 'PATIO_DOOR',
+    3: 'STORM_DOOR',
+    5: 'STORM_WINDOW',
+    7: 'PRIMARY_WINDOW'
+};
+
+const PRODUCT_COLOR = {
+    'BLACK': 1,
+    'BRONZE': 2,
+    'SANDSTONE': 3,
+    'WHITE': 4,
+    'TAN': 5,
+    'MILL': 6
+};
+
+const PRODUCT_COLOR_REVERSE = {
+    1: 'BLACK',
+    2: 'BRONZE',
+    3: 'SANDSTONE',
+    4: 'WHITE',
+    5: 'TAN',
+    6: 'MILL'
+};
+
+const PRODUCT_MATERIAL = {
+    'ALUMINUM': 1,
+    'VINYL': 2
+};
+
+const PRODUCT_MATERIAL_REVERSE = {
+    1: 'ALUMINUM',
+    2: 'VINYL'
+};
+
+// Hardware Fields (5 bits each, 0-31)
+const HARDWARE_TYPE = {
+    'NONE': 0,
+    'LEVER': 1,
+    'PULL': 2,
+    'PULL_HANDLE': 3,
+    'DEADBOLT': 4,
+    'HINGE': 5
+};
+
+const HARDWARE_TYPE_REVERSE = {
+    0: 'NONE',
+    1: 'LEVER',
+    2: 'PULL',
+    3: 'PULL_HANDLE',
+    4: 'DEADBOLT',
+    5: 'HINGE'
+};
+
+const HARDWARE_STYLE = {
+    'NONE': 0,
+    'STANDARD': 1,
+    'PUSH': 2,
+    'ALTERNATIVE': 3,
+    'CONTEMPORARY': 4,
+    'TRADITIONAL': 5
+};
+
+const HARDWARE_STYLE_REVERSE = {
+    0: 'NONE',
+    1: 'STANDARD',
+    2: 'PUSH',
+    3: 'ALTERNATIVE',
+    4: 'CONTEMPORARY',
+    5: 'TRADITIONAL'
+};
+
+const HARDWARE_COLOR = {
+    'NONE': 0,
+    'BRASS': 1,
+    'WHITE': 2,
+    'BLACK': 3,
+    'SATIN': 4,
+    'NICKEL': 5,
+    'BRONZE': 6
+};
+
+const HARDWARE_COLOR_REVERSE = {
+    0: 'NONE',
+    1: 'BRASS',
+    2: 'WHITE',
+    3: 'BLACK',
+    4: 'SATIN',
+    5: 'NICKEL',
+    6: 'BRONZE'
+};
+
+// ============================================================================
+// ENCODING FUNCTIONS
+// ============================================================================
+
+/**
+ * Encode a hardware configuration into a 4-character hex string
+ * Uses 5 bits per field (32 values each)
+ * 
+ * @param {number} type - Hardware type (0-31)
+ * @param {number} style - Hardware style (0-31)
+ * @param {number} color - Hardware color (0-31)
+ * @returns {string} 4-character hex string (e.g., "0421")
+ */
+function encodeHardware(type, style, color) {
+    // Validate inputs
+    if (type < 0 || type > 31) throw new Error(`Invalid hardware type: ${type} (must be 0-31)`);
+    if (style < 0 || style > 31) throw new Error(`Invalid hardware style: ${style} (must be 0-31)`);
+    if (color < 0 || color > 31) throw new Error(`Invalid hardware color: ${color} (must be 0-31)`);
+    
+    // Pack into 16 bits: [reserved(1)][type(5)][style(5)][color(5)]
+    const value = ((type & 0x1F) << 10) |    // Bits 10-14
+                  ((style & 0x1F) << 5) |     // Bits 5-9
+                  (color & 0x1F);             // Bits 0-4
+    
+    return value.toString(16).toUpperCase().padStart(4, '0');
+}
+
+/**
+ * Encode a complete product configuration into a URL string
+ * 
+ * @param {Object} config - Product configuration
+ * @param {number} config.type - Product type (0-15)
+ * @param {number} config.color - Product color (0-15)
+ * @param {number} config.material - Product material (0-15)
+ * @param {Array<Object>} config.hardware - Array of hardware items (optional)
+ * @param {number} config.hardware[].type - Hardware type (0-31)
+ * @param {number} config.hardware[].style - Hardware style (0-31)
+ * @param {number} config.hardware[].color - Hardware color (0-31)
+ * @returns {string} Encoded URL string (e.g., "0-1-4-1-0421")
+ */
+function encodeProduct(config) {
+    // Validate main attributes
+    if (config.type < 0 || config.type > 15) {
+        throw new Error(`Invalid product type: ${config.type} (must be 0-15)`);
+    }
+    if (config.color < 0 || config.color > 15) {
+        throw new Error(`Invalid product color: ${config.color} (must be 0-15)`);
+    }
+    if (config.material < 0 || config.material > 15) {
+        throw new Error(`Invalid product material: ${config.material} (must be 0-15)`);
+    }
+    
+    // Build base string: version-type-color-material
+    const parts = [
+        ENCODING_VERSION.toString(16).toUpperCase(),
+        config.type.toString(16).toUpperCase(),
+        config.color.toString(16).toUpperCase(),
+        config.material.toString(16).toUpperCase()
+    ];
+    
+    // Add hardware items if present
+    if (config.hardware && config.hardware.length > 0) {
+        config.hardware.forEach(hw => {
+            parts.push(encodeHardware(hw.type, hw.style, hw.color));
+        });
+    }
+    
+    return parts.join('-');
+}
+
+/**
+ * Encode using named constants (convenience function)
+ * 
+ * @param {Object} config - Product configuration with named values
+ * @param {string} config.type - Product type name (e.g., 'PATIO_DOOR')
+ * @param {string} config.color - Color name (e.g., 'WHITE')
+ * @param {string} config.material - Material name (e.g., 'ALUMINUM')
+ * @param {Array<Object>} config.hardware - Array of hardware items (optional)
+ * @returns {string} Encoded URL string
+ */
+function encodeProductByName(config) {
+    const numericConfig = {
+        type: PRODUCT_TYPE[config.type],
+        color: PRODUCT_COLOR[config.color],
+        material: PRODUCT_MATERIAL[config.material],
+        hardware: []
+    };
+    
+    if (config.hardware && config.hardware.length > 0) {
+        numericConfig.hardware = config.hardware.map(hw => ({
+            type: HARDWARE_TYPE[hw.type],
+            style: HARDWARE_STYLE[hw.style],
+            color: HARDWARE_COLOR[hw.color]
+        }));
+    }
+    
+    return encodeProduct(numericConfig);
+}
+
+// ============================================================================
+// DECODING FUNCTIONS
+// ============================================================================
+
+/**
+ * Decode a hardware hex string back to its components
+ * 
+ * @param {string} hex - 4-character hex string (e.g., "0421")
+ * @returns {Object} Decoded hardware configuration
+ */
+function decodeHardware(hex) {
+    if (typeof hex !== 'string' || hex.length !== 4) {
+        throw new Error(`Invalid hardware hex string: ${hex} (must be 4 characters)`);
+    }
+    
+    const value = parseInt(hex, 16);
+    
+    if (isNaN(value)) {
+        throw new Error(`Invalid hex value: ${hex}`);
+    }
+    
+    return {
+        type: (value >> 10) & 0x1F,     // Extract bits 10-14
+        style: (value >> 5) & 0x1F,     // Extract bits 5-9
+        color: value & 0x1F             // Extract bits 0-4
+    };
+}
+
+/**
+ * Decode a complete product URL string
+ * 
+ * @param {string} encodedString - Encoded URL string (e.g., "0-1-4-1-0421")
+ * @returns {Object} Decoded product configuration
+ */
+function decodeProduct(encodedString) {
+    if (typeof encodedString !== 'string') {
+        throw new Error('Invalid encoded string: must be a string');
+    }
+    
+    const parts = encodedString.split('-');
+    
+    if (parts.length < 4) {
+        throw new Error(`Invalid encoded string: ${encodedString} (must have at least 4 parts)`);
+    }
+    
+    // Parse version
+    const version = parseInt(parts[0], 16);
+    if (version !== ENCODING_VERSION) {
+        throw new Error(`Unsupported encoding version: ${version} (current: ${ENCODING_VERSION})`);
+    }
+    
+    // Parse main attributes
+    const config = {
+        version: version,
+        type: parseInt(parts[1], 16),
+        color: parseInt(parts[2], 16),
+        material: parseInt(parts[3], 16),
+        hardware: []
+    };
+    
+    // Parse hardware items (if present)
+    for (let i = 4; i < parts.length; i++) {
+        config.hardware.push(decodeHardware(parts[i]));
+    }
+    
+    return config;
+}
+
+/**
+ * Decode and return named values (convenience function)
+ * 
+ * @param {string} encodedString - Encoded URL string
+ * @returns {Object} Decoded product with named values
+ */
+function decodeProductToNames(encodedString) {
+    const numeric = decodeProduct(encodedString);
+    
+    return {
+        version: numeric.version,
+        type: PRODUCT_TYPE_REVERSE[numeric.type] || `UNKNOWN_${numeric.type}`,
+        color: PRODUCT_COLOR_REVERSE[numeric.color] || `UNKNOWN_${numeric.color}`,
+        material: PRODUCT_MATERIAL_REVERSE[numeric.material] || `UNKNOWN_${numeric.material}`,
+        hardware: numeric.hardware.map(hw => ({
+            type: HARDWARE_TYPE_REVERSE[hw.type] || `UNKNOWN_${hw.type}`,
+            style: HARDWARE_STYLE_REVERSE[hw.style] || `UNKNOWN_${hw.style}`,
+            color: HARDWARE_COLOR_REVERSE[hw.color] || `UNKNOWN_${hw.color}`
+        }))
+    };
+}
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Get the binary representation of a hex string (for debugging)
+ * 
+ * @param {string} hex - Hex string
+ * @returns {string} Binary string with spaces every 4 bits
+ */
+function hexToBinary(hex) {
+    const value = parseInt(hex, 16);
+    const binary = value.toString(2).padStart(16, '0');
+    return binary.match(/.{1,4}/g).join(' ');
+}
+
+/**
+ * Validate that a configuration uses only defined values
+ * 
+ * @param {Object} config - Product configuration
+ * @returns {Object} Validation result with errors array
+ */
+function validateConfiguration(config) {
+    const errors = [];
+    
+    if (!PRODUCT_TYPE_REVERSE[config.type]) {
+        errors.push(`Invalid product type: ${config.type}`);
+    }
+    if (!PRODUCT_COLOR_REVERSE[config.color]) {
+        errors.push(`Invalid product color: ${config.color}`);
+    }
+    if (!PRODUCT_MATERIAL_REVERSE[config.material]) {
+        errors.push(`Invalid product material: ${config.material}`);
+    }
+    
+    if (config.hardware) {
+        config.hardware.forEach((hw, index) => {
+            if (!HARDWARE_TYPE_REVERSE[hw.type]) {
+                errors.push(`Invalid hardware ${index + 1} type: ${hw.type}`);
+            }
+            if (!HARDWARE_STYLE_REVERSE[hw.style]) {
+                errors.push(`Invalid hardware ${index + 1} style: ${hw.style}`);
+            }
+            if (!HARDWARE_COLOR_REVERSE[hw.color]) {
+                errors.push(`Invalid hardware ${index + 1} color: ${hw.color}`);
+            }
+        });
+    }
+    
+    return {
+        valid: errors.length === 0,
+        errors: errors
+    };
+}
+
+// ============================================================================
+// EXPORTS (for Node.js / Module usage)
+// ============================================================================
+
+if (typeof module !== 'undefined' && module.exports) {
+    module.exports = {
+        // Constants
+        ENCODING_VERSION,
+        PRODUCT_TYPE,
+        PRODUCT_COLOR,
+        PRODUCT_MATERIAL,
+        HARDWARE_TYPE,
+        HARDWARE_STYLE,
+        HARDWARE_COLOR,
+        
+        // Encoding functions
+        encodeHardware,
+        encodeProduct,
+        encodeProductByName,
+        
+        // Decoding functions
+        decodeHardware,
+        decodeProduct,
+        decodeProductToNames,
+        
+        // Utilities
+        hexToBinary,
+        validateConfiguration
+    };
+}
+
+// ============================================================================
+// EXAMPLE USAGE
+// ============================================================================
+
+/*
+// Example 1: Encode by numeric values
+const encoded1 = encodeProduct({
+    type: 1,        // Patio Door
+    color: 4,       // White
+    material: 1,    // Aluminum
+    hardware: [
+        { type: 1, style: 1, color: 1 }  // Lever, Standard, Brass
+    ]
+});
+console.log(encoded1); // "0-1-4-1-0421"
+
+// Example 2: Encode by named values
+const encoded2 = encodeProductByName({
+    type: 'STORM_DOOR',
+    color: 'WHITE',
+    material: 'ALUMINUM',
+    hardware: [
+        { type: 'LEVER', style: 'STANDARD', color: 'BRASS' },
+        { type: 'PULL_HANDLE', style: 'ALTERNATIVE', color: 'SATIN' }
+    ]
+});
+console.log(encoded2); // "0-3-4-1-0421-0C64"
+
+// Example 3: Decode back to numeric values
+const decoded1 = decodeProduct("0-1-4-1-0421");
+console.log(decoded1);
+// { version: 0, type: 1, color: 4, material: 1, hardware: [{ type: 1, style: 1, color: 1 }] }
+
+// Example 4: Decode to named values
+const decoded2 = decodeProductToNames("0-3-4-1-0421-0C64");
+console.log(decoded2);
+// {
+//   version: 0,
+//   type: 'STORM_DOOR',
+//   color: 'WHITE',
+//   material: 'ALUMINUM',
+//   hardware: [
+//     { type: 'LEVER', style: 'STANDARD', color: 'BRASS' },
+//     { type: 'PULL_HANDLE', style: 'ALTERNATIVE', color: 'SATIN' }
+//   ]
+// }
+
+// Example 5: Debug hardware encoding
+const hwHex = encodeHardware(3, 12, 20);
+console.log(hwHex);                    // "0D94"
+console.log(hexToBinary(hwHex));       // "0000 1101 1001 0100"
+console.log(decodeHardware(hwHex));    // { type: 3, style: 12, color: 20 }
+
+// Example 6: Validate configuration
+const validation = validateConfiguration({
+    type: 1, color: 4, material: 1,
+    hardware: [{ type: 1, style: 1, color: 1 }]
+});
+console.log(validation); // { valid: true, errors: [] }
+*/