dolphin-client 1.0.5 → 1.0.9

package/.vscode/dolphin-tags.json

@@ -0,0 +1,558 @@
+{
+  "version": 1.1,
+  "tags": [
+    {
+      "name": "dolphin-accordion",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-avatar",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-checkbox",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-tabs",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-login",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-register",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-form-floating",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-form-standard",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-table",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-toast",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-modal",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-button",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-card",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-navbar",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-alert",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-badge",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-header",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-footer",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-grid",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-dashboard",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-switch",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-tooltip",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-slider",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-dropdown",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-popover",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-skeleton",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-progress",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-theme-bar",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-drawer",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-breadcrumbs",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-pagination",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-steps",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-hero",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-pricing",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-carousel",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-timeline",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-dropzone",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-chat",
+      "description": "Dolphin CLI Component"
+    },
+    {
+      "name": "dolphin-rating",
+      "description": "Dolphin CLI Component"
+    }
+  ],
+  "globalAttributes": [
+    {
+      "name": "class",
+      "valueSet": "dolphin-classes"
+    },
+    {
+      "name": "className",
+      "valueSet": "dolphin-classes"
+    },
+    {
+      "name": "data-import",
+      "description": "Imports an HTML fragment recursively from the specified relative path or URL."
+    },
+    {
+      "name": "data-api-get",
+      "description": "Performs a GET request to the specified API URL and renders it."
+    },
+    {
+      "name": "data-rt-template",
+      "description": "Specifies the CSS selector of the template to use (e.g., #product)."
+    },
+    {
+      "name": "data-rt-bind",
+      "description": "Binds the HTML content or properties to a specific state or API response."
+    },
+    {
+      "name": "data-store-write",
+      "description": "Binds input changes to write to the specified store state (e.g., store.property)."
+    },
+    {
+      "name": "data-store-read",
+      "description": "Binds element to read/display state from the specified store state (e.g., store.property)."
+    },
+    {
+      "name": "data-rt-validate",
+      "description": "Specifies validation rules for the input (e.g., required, email)."
+    },
+    {
+      "name": "data-api-submit",
+      "description": "Submits form data to the specified API URL (e.g., POST /api/submit)."
+    },
+    {
+      "name": "data-api-result",
+      "description": "Saves the API submission result to the specified state path."
+    },
+    {
+      "name": "data-api-redirect",
+      "description": "URL to redirect the user to after a successful API submission."
+    },
+    {
+      "name": "data-api-reload",
+      "description": "Reloads the page after a successful API submission."
+    },
+    {
+      "name": "data-rt-type",
+      "description": "Specifies the rendering type, such as 'context'."
+    },
+    {
+      "name": "data-rt-payload",
+      "description": "Payload JSON string to pass with events (e.g., '{{id}}')."
+    },
+    {
+      "name": "data-api-payload",
+      "description": "Payload JSON string to send with API events."
+    },
+    {
+      "name": "data-rt-debounce",
+      "description": "Time in milliseconds to debounce inputs before triggering an action."
+    },
+    {
+      "name": "data-rt-click",
+      "description": "Publishes a custom Dolphin event on click."
+    },
+    {
+      "name": "data-rt-change",
+      "description": "Publishes a custom Dolphin event on change."
+    },
+    {
+      "name": "data-rt-submit",
+      "description": "Publishes a custom Dolphin event on form submit."
+    },
+    {
+      "name": "data-rt-input",
+      "description": "Publishes a custom Dolphin event on input."
+    },
+    {
+      "name": "data-rt-keydown",
+      "description": "Publishes a custom Dolphin event on keydown."
+    },
+    {
+      "name": "data-rt-keyup",
+      "description": "Publishes a custom Dolphin event on keyup."
+    },
+    {
+      "name": "data-rt-dblclick",
+      "description": "Publishes a custom Dolphin event on double click."
+    },
+    {
+      "name": "data-rt-focus",
+      "description": "Publishes a custom Dolphin event on focus."
+    },
+    {
+      "name": "data-rt-blur",
+      "description": "Publishes a custom Dolphin event on blur."
+    },
+    {
+      "name": "data-rt-mouseenter",
+      "description": "Publishes a custom Dolphin event on mouse enter."
+    },
+    {
+      "name": "data-rt-mouseleave",
+      "description": "Publishes a custom Dolphin event on mouse leave."
+    },
+    {
+      "name": "data-api-click",
+      "description": "Performs an API request on click (e.g., POST /api/like)."
+    },
+    {
+      "name": "data-api-change",
+      "description": "Performs an API request on change."
+    },
+    {
+      "name": "data-api-input",
+      "description": "Performs an API request on input."
+    },
+    {
+      "name": "data-api-keydown",
+      "description": "Performs an API request on keydown."
+    },
+    {
+      "name": "data-api-keyup",
+      "description": "Performs an API request on keyup."
+    },
+    {
+      "name": "data-api-dblclick",
+      "description": "Performs an API request on double click."
+    },
+    {
+      "name": "data-api-focus",
+      "description": "Performs an API request on focus."
+    },
+    {
+      "name": "data-api-blur",
+      "description": "Performs an API request on blur."
+    },
+    {
+      "name": "data-api-mouseenter",
+      "description": "Performs an API request on mouse enter."
+    },
+    {
+      "name": "data-api-mouseleave",
+      "description": "Performs an API request on mouse leave."
+    },
+    {
+      "name": "data-store-click",
+      "description": "Runs a Dolphin store action expression on click (e.g., app.count++)."
+    },
+    {
+      "name": "data-store-change",
+      "description": "Runs a Dolphin store action expression on change."
+    },
+    {
+      "name": "data-store-submit",
+      "description": "Runs a Dolphin store action expression on submit."
+    },
+    {
+      "name": "data-store-input",
+      "description": "Runs a Dolphin store action expression on input."
+    },
+    {
+      "name": "data-store-keydown",
+      "description": "Runs a Dolphin store action expression on keydown."
+    },
+    {
+      "name": "data-store-keyup",
+      "description": "Runs a Dolphin store action expression on keyup."
+    },
+    {
+      "name": "data-store-dblclick",
+      "description": "Runs a Dolphin store action expression on double click."
+    },
+    {
+      "name": "data-store-focus",
+      "description": "Runs a Dolphin store action expression on focus."
+    },
+    {
+      "name": "data-store-blur",
+      "description": "Runs a Dolphin store action expression on blur."
+    },
+    {
+      "name": "data-store-mouseenter",
+      "description": "Runs a Dolphin store action expression on mouse enter."
+    },
+    {
+      "name": "data-store-mouseleave",
+      "description": "Runs a Dolphin store action expression on mouse leave."
+    },
+    {
+      "name": "data-rt-text",
+      "description": "Binds text content to a property in the closest rendering context."
+    },
+    {
+      "name": "data-rt-html",
+      "description": "Binds HTML content to a property in the closest rendering context."
+    },
+    {
+      "name": "data-rt-attr",
+      "description": "Binds attributes dynamically (e.g., src:imageUrl, href:linkUrl)."
+    },
+    {
+      "name": "data-rt-class",
+      "description": "Binds CSS classes conditionally (e.g., active:isActive)."
+    },
+    {
+      "name": "data-rt-if",
+      "description": "Shows the element only if the specified context property is truthy."
+    },
+    {
+      "name": "data-rt-hide",
+      "description": "Hides the element if the specified context property is truthy."
+    },
+    {
+      "name": "data-rt-filter",
+      "description": "Filters the rendered data array (e.g., status==completed)."
+    },
+    {
+      "name": "data-rt-search",
+      "description": "Searches the rendered data array (e.g., title==searchQuery)."
+    },
+    {
+      "name": "data-rt-sort",
+      "description": "Sorts the rendered data array (e.g., price.asc or popular)."
+    }
+  ],
+  "valueSets": [
+    {
+      "name": "dolphin-classes",
+      "values": [
+        {
+          "name": "dolphin-accordion",
+          "description": "Dolphin CLI Component (dolphin-accordion.html)"
+        },
+        {
+          "name": "dolphin-avatar",
+          "description": "Dolphin CLI Component (dolphin-avatar.html)"
+        },
+        {
+          "name": "dolphin-checkbox",
+          "description": "Dolphin CLI Component (dolphin-checkbox.html)"
+        },
+        {
+          "name": "dolphin-tabs",
+          "description": "Dolphin CLI Component (dolphin-tabs.html)"
+        },
+        {
+          "name": "dolphin-login",
+          "description": "Dolphin CLI Component (dolphin-login.html)"
+        },
+        {
+          "name": "dolphin-register",
+          "description": "Dolphin CLI Component (dolphin-register.html)"
+        },
+        {
+          "name": "dolphin-form-floating",
+          "description": "Dolphin CLI Component (dolphin-form-floating.html)"
+        },
+        {
+          "name": "dolphin-form-standard",
+          "description": "Dolphin CLI Component (dolphin-form-standard.html)"
+        },
+        {
+          "name": "dolphin-table",
+          "description": "Dolphin CLI Component (dolphin-table.html)"
+        },
+        {
+          "name": "dolphin-toast",
+          "description": "Dolphin CLI Component (dolphin-toast.html)"
+        },
+        {
+          "name": "dolphin-modal",
+          "description": "Dolphin CLI Component (dolphin-modal.html)"
+        },
+        {
+          "name": "dolphin-button",
+          "description": "Dolphin CLI Component (dolphin-button.html)"
+        },
+        {
+          "name": "dolphin-card",
+          "description": "Dolphin CLI Component (dolphin-card.html)"
+        },
+        {
+          "name": "dolphin-navbar",
+          "description": "Dolphin CLI Component (dolphin-navbar.html)"
+        },
+        {
+          "name": "dolphin-alert",
+          "description": "Dolphin CLI Component (dolphin-alert.html)"
+        },
+        {
+          "name": "dolphin-badge",
+          "description": "Dolphin CLI Component (dolphin-badge.html)"
+        },
+        {
+          "name": "dolphin-header",
+          "description": "Dolphin CLI Component (dolphin-header.html)"
+        },
+        {
+          "name": "dolphin-footer",
+          "description": "Dolphin CLI Component (dolphin-footer.html)"
+        },
+        {
+          "name": "dolphin-grid",
+          "description": "Dolphin CLI Component (dolphin-grid.html)"
+        },
+        {
+          "name": "dolphin-dashboard",
+          "description": "Dolphin CLI Component (dolphin-dashboard.html)"
+        },
+        {
+          "name": "dolphin-switch",
+          "description": "Dolphin CLI Component (dolphin-switch.html)"
+        },
+        {
+          "name": "dolphin-tooltip",
+          "description": "Dolphin CLI Component (dolphin-tooltip.html)"
+        },
+        {
+          "name": "dolphin-slider",
+          "description": "Dolphin CLI Component (dolphin-slider.html)"
+        },
+        {
+          "name": "dolphin-dropdown",
+          "description": "Dolphin CLI Component (dolphin-dropdown.html)"
+        },
+        {
+          "name": "dolphin-popover",
+          "description": "Dolphin CLI Component (dolphin-popover.html)"
+        },
+        {
+          "name": "dolphin-skeleton",
+          "description": "Dolphin CLI Component (dolphin-skeleton.html)"
+        },
+        {
+          "name": "dolphin-progress",
+          "description": "Dolphin CLI Component (dolphin-progress.html)"
+        },
+        {
+          "name": "dolphin-theme-bar",
+          "description": "Dolphin CLI Component (dolphin-theme-bar.html)"
+        },
+        {
+          "name": "dolphin-drawer",
+          "description": "Dolphin CLI Component (dolphin-drawer.html)"
+        },
+        {
+          "name": "dolphin-breadcrumbs",
+          "description": "Dolphin CLI Component (dolphin-breadcrumbs.html)"
+        },
+        {
+          "name": "dolphin-pagination",
+          "description": "Dolphin CLI Component (dolphin-pagination.html)"
+        },
+        {
+          "name": "dolphin-steps",
+          "description": "Dolphin CLI Component (dolphin-steps.html)"
+        },
+        {
+          "name": "dolphin-hero",
+          "description": "Dolphin CLI Component (dolphin-hero.html)"
+        },
+        {
+          "name": "dolphin-pricing",
+          "description": "Dolphin CLI Component (dolphin-pricing.html)"
+        },
+        {
+          "name": "dolphin-carousel",
+          "description": "Dolphin CLI Component (dolphin-carousel.html)"
+        },
+        {
+          "name": "dolphin-timeline",
+          "description": "Dolphin CLI Component (dolphin-timeline.html)"
+        },
+        {
+          "name": "dolphin-dropzone",
+          "description": "Dolphin CLI Component (dolphin-dropzone.html)"
+        },
+        {
+          "name": "dolphin-chat",
+          "description": "Dolphin CLI Component (dolphin-chat.html)"
+        },
+        {
+          "name": "dolphin-rating",
+          "description": "Dolphin CLI Component (dolphin-rating.html)"
+        }
+      ]
+    }
+  ]
+}

package/README.md

@@ -29,13 +29,17 @@ By breathing life back into standard HTML, we have resurrected the simplicity of
 
 ## Features
 
+- **Universal Backend Compatibility**: Native out-of-the-box support for PHP (Laravel, CakePHP, WordPress) and Node.js (Express, NestJS, Fastify). Auto-extracts/injects CSRF tokens and nonces, normalizes multi-format validation error payloads directly into reactive forms, and supports HTTP method spoofing (`_method`) and subfolder base URLs automatically.
+- **HTML Component Imports (`data-import`)**: Declaratively import reusable layouts (e.g. `header.html`, `footer.html`) dynamically in pure HTML with robust concurrent promise caching, nested rendering, and circular dependency checks.
+- **Instant SPA Viewport Router (`data-spa`)**: Converts static pages into highly responsive Single Page Applications (SPAs) with zero manual JS. High-jacks links, swaps viewports dynamically with smooth fading transitions, and updates page titles and history navigation (`popstate`).
 - **Hookless Reactivity**: Bind topics to DOM elements via HTML data attributes—no React, Vue, or Angular state management required.
 - **Svelte-Style Templates Compiler**: Native browser compiler supporting Svelte-style loop blocks (`{#each ... as ...}`), multi-level nested conditionals (`{#if} / {:else if} / {:else}`), loop indices (`index`), optional chaining, and dynamic attribute interpolation.
 - **Unified Event Binding**: Loop-based browser event handling for values (`data-rt-push`) and actions (`data-rt-[event]` / `data-api-[event]`).
 - **Context API/Prop drilling in Pure DOM**: Crawls up the DOM tree (`getClosestContext`) to fetch parent contexts and inject parameters.
 - **REST API + Realtime Hybrid Support**: Evaluates templates (`data-rt-template`) on initial HTTP fetches (`data-api-get`) and transitions seamlessly to real-time WebSockets on connection.
 - **WebRTC Intercom Signaling**: Built-in methods to handle peer connections, track negotiation, ICE candidates, and signaling.
-- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs (~39KB compressed bundle!).
+- **DolphinStore JS API & React Integration**: Programmatic store query, filtering (`where`), sorting (`orderBy`), and live collection syncing with auto-REST/WS fallback. Integrates seamlessly with React (class or hook components) using native external store subscriptions.
+- **Ultralight weight**: Zero external dependencies, pure browser-native runtime APIs (~47KB compressed bundle!).
 
 ---
 
@@ -90,6 +94,30 @@ Inside your HTML, simply link them locally:
 
 ---
 
+## 🧠 VS Code Autocomplete (IntelliSense)
+
+Get instant HTML attribute suggestions for all Dolphin Client attributes (`data-api-get`, `data-rt-click`, `data-store-write`, etc.) directly inside VS Code!
+
+### For NPM Users
+Autocomplete is set up **automatically** when you install:
+```bash
+npm install dolphin-client
+```
+That's it! Reload VS Code window (`Ctrl + Shift + P` → `Developer: Reload Window`) and start typing `data-` to see suggestions.
+
+### For CDN / Direct Download Users
+Run this **one-time command** inside your project folder:
+```bash
+npx dolphin-client
+```
+
+This will automatically generate `.vscode/settings.json` and `.vscode/dolphin-tags.json` in your project, enabling full HTML attribute autocomplete in VS Code.
+
+> [!TIP]
+> After running the command, reload VS Code (`Ctrl + Shift + P` → `Developer: Reload Window`) to activate autocomplete. You only need to run this **once per project**!
+
+---
+
 ## Interactive Examples Guide
 
 Below are clean, ready-to-use HTML examples for the core features of Dolphin Client. Because Dolphin supports **Zero-Configuration Auto-Initialization**, these will run instantly!
@@ -177,7 +205,26 @@ Manage local stores and run complex calculations, conditions, and toggles **dire
 <button data-store-click="app.darkMode = !app.darkMode">Toggle Dark Mode</button>
 ```
 
-### 5. Silent Zero-Configuration Auto-Initialization
+### 5. JavaScript Store API & React Integration
+Query and filter dynamic collections programmatically in JS or sync them with React without state hooks:
+
+```javascript
+// Access the reactive store (auto-fetches GET /users and subscribes to WS db:sync/users)
+const users = dolphin.store.users;
+
+// Dynamic client-side filtering and sorting
+const activeAdmins = users.where(u => u.active && u.role === 'admin').orderBy('name', 'asc');
+
+// Subscribe to store changes manually
+const unsubscribe = dolphin.store.subscribe(() => {
+  console.log("Updated admin count:", activeAdmins.items.length);
+});
+
+// Clean up when no longer needed to prevent memory leaks
+dolphin.store.destroy();
+```
+
+### 6. Silent Zero-Configuration Auto-Initialization
 When loaded via a standard `<script>` tag in browser environments, Dolphin Client automatically boots up a default client instance as `window.dolphin` on `DOMContentLoaded`.
 
 For debugging, pass `data-debug="true"` on your script tag to turn on gorgeous, color-coded logging in your developer console for all API calls, WebSocket events, and Store updates:

package/bin/cli.cjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// This CLI runs when users execute: npx dolphin-client
+// It sets up the VS Code HTML Custom Data configurations for autocomplete automatically!
+
+try {
+    const hostRoot = process.cwd();
+    const vscodeDir = path.join(hostRoot, '.vscode');
+
+    console.log('🐬 [Dolphin Client CLI] Setting up VS Code autocomplete...');
+
+    // 1. Ensure .vscode directory exists in user's current directory
+    if (!fs.existsSync(vscodeDir)) {
+        fs.mkdirSync(vscodeDir, { recursive: true });
+        console.log('   - Created .vscode directory.');
+    }
+
+    // 2. Copy the dolphin-tags.json file from the npm package to the user's project
+    const sourceTags = path.resolve(__dirname, '../.vscode/dolphin-tags.json');
+    const destTags = path.join(vscodeDir, 'dolphin-tags.json');
+
+    if (fs.existsSync(sourceTags)) {
+        fs.copyFileSync(sourceTags, destTags);
+        console.log('   - Copied dolphin-tags.json config.');
+    } else {
+        console.warn('   ⚠️  Warning: dolphin-tags.json source file not found.');
+    }
+
+    // 3. Register the path in the user's project settings.json
+    const settingsPath = path.join(vscodeDir, 'settings.json');
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        } catch (e) {
+            settings = {};
+        }
+    }
+
+    if (!settings['html.customData']) {
+        settings['html.customData'] = [];
+    }
+
+    const relativePath = '.vscode/dolphin-tags.json';
+    if (!settings['html.customData'].includes(relativePath)) {
+        settings['html.customData'].push(relativePath);
+        fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
+        console.log('   - Registered custom HTML data in settings.json.');
+    } else {
+        console.log('   - dolphin-tags.json was already registered.');
+    }
+
+    console.log('\n\x1b[36m%s\x1b[0m', '✅ [Success] VS Code autocomplete successfully set up for Dolphin Client!');
+    console.log('\x1b[33m%s\x1b[0m', '👉 Tip: Run "Developer: Reload Window" in VS Code to activate autocomplete.');
+} catch (err) {
+    console.error('❌ [Error] Failed to set up VS Code autocomplete:', err.message);
+}