Bump version to 1.3.0 in manifest.json

Enhance configuration handling with validation and normalization.

README.md

@@ -1,36 +1,135 @@
-## Installation
+# Shopping List Manager
 
-### 1. Install via HACS
+A custom Home Assistant integration that provides an enhanced shopping list experience, including a companion Lovelace card for managing items directly from your dashboard.
 
-[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=thekiwismarthome&repository=shopping-list-manager&category=integration)
+---
 
-Click the button above or manually add the custom repository in HACS.
-Restart HA
+## Features
 
-### 2. Add the Card Resource
+- 📋 Manage shopping list items from Home Assistant
+- 🔌 WebSocket-based backend (no polling entities)
+- 🖥️ Custom Lovelace card
+- ⚙️ UI-based configuration (Config Flow)
+- 🚀 Compatible with Home Assistant **2024.8+**
 
-After installing via HACS, add the frontend resource:
+---
 
-1. Go to Settings → Dashboards
-2. Click ⋮ (three dots, top right) → Resources
-3. Click "+ Add Resource"
-4. URL: `/local/community/shopping-list-manager/shopping_list_card.js`
-5. Resource type: JavaScript Module
-6. Click "Create"
+## 1. Installation (HACS)
 
-### 3. Add the Integration
+[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](
+https://my.home-assistant.io/redirect/hacs_repository/?owner=thekiwismarthome&repository=shopping-list-manager&category=integration
+)
 
-[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](https://my.home-assistant.io/redirect/config_flow_start/?domain=shopping_list_manager)
+Click the button above **or** follow the manual steps below.
 
-Click the button above or manually add via Settings → Devices & Services.
+1. Open **HACS**
+2. Go to **Integrations**
+3. Click **⋮ → Custom repositories**
+4. Add this repository:
+   - **Repository:** `https://github.com/thekiwismarthome/shopping-list-manager`
+   - **Category:** Integration
+5. Install **Shopping List Manager**
+6. **Restart Home Assistant**
+
+---
+
+## 2. Install the Lovelace Card Resource (Required)
+
+The Lovelace card JavaScript file is included with the integration, but **must be copied manually** to the `www` directory so Home Assistant can load it.
+
+### Step 1: Copy the card file
+
+Run the following command (via SSH, Terminal add-on, or container shell):
+
+```bash
+mkdir -p /config/www/community/shopping_list_card && \
+cp /config/custom_components/shopping_list_manager/frontend/shopping_list_card.js \
+   /config/www/community/shopping_list_card/shopping_list_card.js
+```
+
+---
+
+### Step 2: Add the resource to Home Assistant
+
+1. Go to **Settings → Dashboards**
+2. Click **⋮ (top right) → Resources**
+3. Click **Add Resource**
+4. Enter:
+
+```text
+URL: /local/community/shopping_list_card/shopping_list_card.js
+Type: JavaScript Module
+```
+
+5. Click **Create**
+6. Refresh your browser (**Ctrl + F5**)
+
+---
+
+## 3. Add the Integration
+
+[![Open your Home Assistant instance and start setting up a new integration.](https://my.home-assistant.io/badges/config_flow_start.svg)](
+https://my.home-assistant.io/redirect/config_flow_start/?domain=shopping_list_manager
+)
+
+Click the button above **or** add it manually:
+
+1. Go to **Settings → Devices & Services**
+2. Click **Add Integration**
+3. Search for **Shopping List Manager**
+4. Follow the setup steps
+
+No YAML configuration is required.
+
+---
+
+## 4. Add the Card to a Dashboard
+
+Add a **Manual** card to your dashboard and use the following YAML:
 
-### 4. Add Card to Dashboard
 ```yaml
 type: custom:shopping-list-card
 title: Shopping List
 list_id: groceries
 ```
 
+Use the **⚙️ cog button** in the card to configure additional settings.
 
-Use the ⚙️ cog button in the card to configure settings.
+---
 
+## Updating
+
+- HACS updates will update the **integration**
+- If the Lovelace card JavaScript changes in a future release, you must **repeat the copy command** above
+
+This is expected behavior for single-repository integrations.
+
+---
+
+## Compatibility Notes
+
+- Designed for **Home Assistant 2024.8+**
+- Uses WebSocket APIs
+- Fully compatible with the **Services → Actions** change introduced in Home Assistant 2024.8
+
+---
+
+## Troubleshooting
+
+If the card does not load:
+
+1. Ensure Home Assistant was restarted after installation
+2. Verify the file exists at:
+
+```
+/config/www/community/shopping_list_card/shopping_list_card.js
+```
+
+3. Confirm the resource URL is correct
+4. Perform a hard browser refresh (**Ctrl + F5**)
+
+---
+
+## License
+
+MIT License

custom_components/shopping_list_manager/frontend/shopping_list_card.js

@@ -112,16 +112,53 @@ class ShoppingListCard extends HTMLElement {
   }
 
   setConfig(config) {
-    this._config = { ...config };  // shallow-copy: HA 2026+ freezes the original
-    // Derive a unique settings key for THIS card instance so each card on
-    // the dashboard keeps its own independent settings in localStorage.
-    // Set `card_id` in YAML for an explicit stable label; otherwise title is used.
-    const id = (config.card_id || config.title || 'shopping_list').toString().trim().toLowerCase().replace(/[^a-z0-9_]/g, '_');
-    this._settingsKey = `shopping_list_settings_${id}`;
-    // Re-load settings now that we have the correct key
-    this._settings = this._loadSettings();
+    if (!config || typeof config !== 'object') {
+      throw new Error('Invalid configuration');
+    }
+  
+    // Normalize + freeze config shape here
+    this._config = {
+      title: config.title ?? 'Shopping List',
+      card_id: config.card_id,
+      products_per_row: config.products_per_row ?? 'auto',
+      layout: config.layout ?? 'grid',
+      haptics: config.haptics ?? 'medium',
+      hide_completed: !!config.hide_completed,
+      compact_headers: !!config.compact_headers
+    };
+  
+    // Derive a stable per-card storage key
+    const idSource =
+      this._config.card_id ||
+      this._config.title ||
+      'shopping_list';
+  
+    const id = idSource
+      .toString()
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9_]/g, '_');
+  
+    const newSettingsKey = `shopping_list_settings_${id}`;
+  
+    // If the card_id / title changed, reload settings
+    if (this._settingsKey !== newSettingsKey) {
+      this._settingsKey = newSettingsKey;
+      this._settings = this._loadSettings();
+    }
+  
+    // First-time init
+    if (!this._settings) {
+      this._settings = this._loadSettings();
+    }
+  
+    // Trigger a re-render if already attached
+    if (this.isConnected) {
+      this._render?.();
+    }
   }
 
+
   /**
    * Load data using Home Assistant's connection.sendMessagePromise
    */
@@ -1941,17 +1978,26 @@ class ShoppingListCard extends HTMLElement {
   }
 
   // Temporarily disabled GUI editor - use YAML configuration
-  // static getConfigElement() {
-  //   return document.createElement('shopping-list-card-editor');
-  // }
-
-  static getStubConfig() {
-    return { title: 'Shopping List' };
+  static getConfigElement() {
+    return document.createElement('shopping-list-card-editor');
   }
-
+  
+  static getStubConfig() {
+    return {
+      type: 'custom:shopping-list-card',
+      title: 'Shopping List',
+      products_per_row: 'auto',
+      layout: 'grid',
+      haptics: 'medium',
+      hide_completed: false,
+      compact_headers: false
+    };
+  }
+  
   getCardSize() {
     return 3;
   }
+
 }
 
 // ── GUI Config Editor ─────────────────────────────────────────

custom_components/shopping_list_manager/manifest.json

@@ -1,7 +1,7 @@
 {
   "domain": "shopping_list_manager",
   "name": "Shopping List Manager",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "documentation": "https://github.com/thekiwismarthome/shopping-list-manager",
   "issue_tracker": "https://github.com/thekiwismarthome/shopping-list-manager/issues",
   "requirements": [],