Add custom data table to Dexie store for user-managed state persistence (#1035)

* Initial plan

* Add custom data table to Dexie store with comprehensive documentation

Co-authored-by: mikebarkmin <[email protected]>

* Update versions and add changeset for custom data store feature

- Bump @hyperbook/markdown to 0.40.0
- Bump hyperbook to 0.66.0
- Bump hyperbook-studio to 0.42.0
- Add changeset file for custom data store feature
- Update CHANGELOG.md files for all affected packages
- Update website changelog with v0.66.0 entry

Co-authored-by: mikebarkmin <[email protected]>

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: mikebarkmin <[email protected]>

Author: Copilot

.changeset/custom-data-store.md

@@ -0,0 +1,15 @@
+---
+"@hyperbook/markdown": minor
+"hyperbook": minor
+"hyperbook-studio": minor
+---
+
+Add custom data table to Dexie store for user-managed state persistence
+
+This adds a new `custom` table to the Hyperbook Dexie store, enabling users to persist arbitrary JSON data in the browser's IndexedDB.
+
+Features:
+- New `custom` table with schema `id, payload` for storing user-defined data
+- Comprehensive documentation in the advanced section showing how to use the API
+- Automatic inclusion in existing export/import functionality
+- Full support for storing and retrieving JSON data using `store.custom.put()` and `store.custom.get()`

packages/hyperbook/CHANGELOG.md

@@ -1,5 +1,25 @@
 # hyperbook
 
+## 0.66.0
+
+### Minor Changes
+
+- Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Add custom data table to Dexie store for user-managed state persistence
+
+  This adds a new `custom` table to the Hyperbook Dexie store, enabling users to persist arbitrary JSON data in the browser's IndexedDB.
+
+  Features:
+
+  - New `custom` table with schema `id, payload` for storing user-defined data
+  - Comprehensive documentation in the advanced section showing how to use the API
+  - Automatic inclusion in existing export/import functionality
+  - Full support for storing and retrieving JSON data using `store.custom.put()` and `store.custom.get()`
+
+### Patch Changes
+
+- Updated dependencies:
+  - @hyperbook/markdown@0.40.0
+
 ## 0.65.0
 
 ### Minor Changes

packages/hyperbook/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperbook",
-  "version": "0.65.0",
+  "version": "0.66.0",
   "author": "Mike Barkmin",
   "homepage": "https://github.com/openpatch/hyperbook#readme",
   "license": "MIT",

packages/markdown/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @hyperbook/markdown
 
+## 0.40.0
+
+### Minor Changes
+
+- Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Add custom data table to Dexie store for user-managed state persistence
+
+  This adds a new `custom` table to the Hyperbook Dexie store, enabling users to persist arbitrary JSON data in the browser's IndexedDB.
+
+  Features:
+
+  - New `custom` table with schema `id, payload` for storing user-defined data
+  - Comprehensive documentation in the advanced section showing how to use the API
+  - Automatic inclusion in existing export/import functionality
+  - Full support for storing and retrieving JSON data using `store.custom.put()` and `store.custom.get()`
+
 ## 0.39.0
 
 ### Minor Changes

packages/markdown/assets/store.js

@@ -28,6 +28,7 @@ store.version(1).stores({
   geogebra: `id,state`,
   learningmap: `id,nodes,x,y,zoom`,
   textinput: `id,text`,
+  custom: `id,payload`,
 });
 var sqlIdeDB = new Dexie("SQL-IDE");
 sqlIdeDB.version(0.1).stores({

packages/markdown/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbook/markdown",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "author": "Mike Barkmin",
   "homepage": "https://github.com/openpatch/hyperbook#readme",
   "license": "MIT",

platforms/vscode/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @hyperbook/vscode-extension
 
+## 0.42.0
+
+### Minor Changes
+
+- Thanks [@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)! - Add custom data table to Dexie store for user-managed state persistence
+
+  This adds a new `custom` table to the Hyperbook Dexie store, enabling users to persist arbitrary JSON data in the browser's IndexedDB.
+
+  Features:
+
+  - New `custom` table with schema `id, payload` for storing user-defined data
+  - Comprehensive documentation in the advanced section showing how to use the API
+  - Automatic inclusion in existing export/import functionality
+  - Full support for storing and retrieving JSON data using `store.custom.put()` and `store.custom.get()`
+
+### Patch Changes
+
+- Updated dependencies:
+  - @hyperbook/markdown@0.40.0
+
 ## 0.41.0
 
 ### Minor Changes

platforms/vscode/package.json

@@ -11,7 +11,7 @@
   },
   "homepage": "https://hyperbook.openpatch.org",
   "main": "./out/extension.js",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "engines": {
     "vscode": "^1.71.0"
   },

website/de/book/advanced/custom-scripts.md

@@ -28,3 +28,107 @@ for (let el of els) {
 ```
 
 <div class="random-color">Am I a Chameleon?</div>
+
+## Verwendung der Hyperbook Store API
+
+Hyperbook stellt eine integrierte Dexie-Datenbank zur Verfügung, mit der du benutzerdefinierte Daten in der IndexedDB des Browsers speichern und abrufen kannst. Dies ist nützlich zum Speichern von Benutzereinstellungen, Fortschrittsverfolgung oder anderen benutzerdefinierten Daten, die nach dem Neuladen der Seite erhalten bleiben sollen.
+
+### Custom Data Tabelle
+
+Der Hyperbook-Store enthält eine `custom`-Tabelle, die speziell für deine benutzerdefinierten Datenanforderungen entwickelt wurde. Das Tabellenschema ist:
+
+- `id` - Eine eindeutige Kennung für deinen Dateneintrag (String)
+- `payload` - Deine benutzerdefinierten Daten, typischerweise als JSON gespeichert
+
+### Daten speichern
+
+Du kannst benutzerdefinierte JSON-Daten mit der Methode `store.custom.put()` speichern:
+
+```js
+// Benutzereinstellungen speichern
+await store.custom.put({
+  id: "user-preferences",
+  payload: JSON.stringify({
+    theme: "dark",
+    fontSize: 16,
+    language: "de"
+  })
+});
+
+// Benutzerfortschritt speichern
+await store.custom.put({
+  id: "chapter-progress",
+  payload: JSON.stringify({
+    currentChapter: 5,
+    completedExercises: [1, 2, 3],
+    lastVisited: new Date().toISOString()
+  })
+});
+```
+
+### Daten abrufen
+
+Du kannst deine Daten mit der Methode `store.custom.get()` abrufen:
+
+```js
+// Benutzereinstellungen abrufen
+const prefs = await store.custom.get("user-preferences");
+if (prefs) {
+  const preferences = JSON.parse(prefs.payload);
+  console.log(preferences.theme); // "dark"
+}
+
+// Benutzerfortschritt abrufen
+const progress = await store.custom.get("chapter-progress");
+if (progress) {
+  const data = JSON.parse(progress.payload);
+  console.log(data.currentChapter); // 5
+}
+```
+
+### Vollständiges Beispiel
+
+Hier ist ein vollständiges Beispiel, das das Speichern und Laden benutzerdefinierter Daten demonstriert:
+
+```js title="user-preferences.js"
+// Einstellungen initialisieren oder laden
+async function initPreferences() {
+  const stored = await store.custom.get("my-app-settings");
+  
+  let settings;
+  if (stored) {
+    settings = JSON.parse(stored.payload);
+  } else {
+    // Standardeinstellungen
+    settings = {
+      notifications: true,
+      autoSave: true,
+      lastLogin: new Date().toISOString()
+    };
+    await savePreferences(settings);
+  }
+  
+  return settings;
+}
+
+// Einstellungen speichern
+async function savePreferences(settings) {
+  await store.custom.put({
+    id: "my-app-settings",
+    payload: JSON.stringify(settings)
+  });
+}
+
+// Beispielverwendung
+initPreferences().then(settings => {
+  console.log("Aktuelle Einstellungen:", settings);
+  
+  // Eine Einstellung aktualisieren
+  settings.notifications = false;
+  savePreferences(settings);
+});
+```
+
+### Datenexport und -import
+
+Deine benutzerdefinierten Daten werden automatisch eingeschlossen, wenn Benutzer ihre Hyperbook-Daten mit der Funktion `hyperbookExport()` exportieren. Ebenso werden sie wiederhergestellt, wenn sie `hyperbookImport()` verwenden. Dadurch wird sichergestellt, dass deine benutzerdefinierten Daten über Browser-Sitzungen hinweg erhalten bleiben und zwischen Geräten übertragen werden können.

website/en/book/advanced/custom-scripts.md

@@ -27,3 +27,107 @@ for (let el of els) {
 ```
 
 <div class="random-color">Am I a Chameleon?</div>
+
+## Using the Hyperbook Store API
+
+Hyperbook provides a built-in Dexie database that allows you to store and retrieve custom data in the browser's IndexedDB. This is useful for persisting user preferences, progress tracking, or any other custom data that should survive page reloads.
+
+### Custom Data Table
+
+The hyperbook store includes a `custom` table specifically designed for your custom data needs. The table schema is:
+
+- `id` - A unique identifier for your data entry (string)
+- `payload` - Your custom data, typically stored as JSON
+
+### Saving Data
+
+You can save custom JSON data using the `store.custom.put()` method:
+
+```js
+// Save user preferences
+await store.custom.put({
+  id: "user-preferences",
+  payload: JSON.stringify({
+    theme: "dark",
+    fontSize: 16,
+    language: "en"
+  })
+});
+
+// Save user progress
+await store.custom.put({
+  id: "chapter-progress",
+  payload: JSON.stringify({
+    currentChapter: 5,
+    completedExercises: [1, 2, 3],
+    lastVisited: new Date().toISOString()
+  })
+});
+```
+
+### Retrieving Data
+
+You can retrieve your data using the `store.custom.get()` method:
+
+```js
+// Get user preferences
+const prefs = await store.custom.get("user-preferences");
+if (prefs) {
+  const preferences = JSON.parse(prefs.payload);
+  console.log(preferences.theme); // "dark"
+}
+
+// Get user progress
+const progress = await store.custom.get("chapter-progress");
+if (progress) {
+  const data = JSON.parse(progress.payload);
+  console.log(data.currentChapter); // 5
+}
+```
+
+### Complete Example
+
+Here's a complete example that demonstrates saving and loading custom data:
+
+```js title="user-preferences.js"
+// Initialize or load preferences
+async function initPreferences() {
+  const stored = await store.custom.get("my-app-settings");
+  
+  let settings;
+  if (stored) {
+    settings = JSON.parse(stored.payload);
+  } else {
+    // Default settings
+    settings = {
+      notifications: true,
+      autoSave: true,
+      lastLogin: new Date().toISOString()
+    };
+    await savePreferences(settings);
+  }
+  
+  return settings;
+}
+
+// Save preferences
+async function savePreferences(settings) {
+  await store.custom.put({
+    id: "my-app-settings",
+    payload: JSON.stringify(settings)
+  });
+}
+
+// Example usage
+initPreferences().then(settings => {
+  console.log("Current settings:", settings);
+  
+  // Update a setting
+  settings.notifications = false;
+  savePreferences(settings);
+});
+```
+
+### Data Export and Import
+
+Your custom data is automatically included when users export their hyperbook data using the `hyperbookExport()` function. Similarly, it will be restored when they use `hyperbookImport()`. This ensures your custom data is preserved across browser sessions and can be transferred between devices.