@gxp-dev/tools 2.0.5

package/docs/building-for-platform.md

@@ -0,0 +1,315 @@
+---
+sidebar_position: 6
+title: Building for Platform
+description: Prepare your plugin for production deployment on the GxP platform
+---
+
+# Building for Platform
+
+This guide covers how to build and prepare your plugin for deployment to the GxP platform.
+
+## Build Command
+
+Run the build command to create a production-ready bundle:
+
+```bash
+gxdev build
+# or
+npm run build
+```
+
+This creates a `dist/` folder with optimized assets:
+
+```
+dist/
+├── assets/
+│   ├── Plugin-[hash].js      # Main plugin bundle
+│   ├── Plugin-[hash].css     # Extracted styles
+│   └── [other chunks]        # Code-split chunks
+├── index.html                # (dev only, not deployed)
+└── manifest.json             # Build manifest
+```
+
+## What Gets Built
+
+The build process:
+
+1. **Compiles Vue SFCs** - Single File Components are compiled to JavaScript
+2. **Bundles dependencies** - Tree-shakes and bundles only what you use
+3. **Extracts CSS** - Styles are extracted to separate files
+4. **Minifies code** - JavaScript and CSS are minified
+5. **Generates hashes** - File names include content hashes for caching
+6. **Creates source maps** - Optional source maps for debugging
+
+## Build Configuration
+
+### vite.config.js
+
+Your project's `vite.config.js` controls the build:
+
+```javascript
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@layouts': path.resolve(__dirname, './theme-layouts'),
+      '@gx-runtime': path.resolve(__dirname, './node_modules/@gramercytech/gx-devtools/runtime'),
+    },
+  },
+  build: {
+    lib: {
+      entry: path.resolve(__dirname, 'src/Plugin.vue'),
+      name: 'GxpPlugin',
+      fileName: (format) => `plugin.${format}.js`,
+    },
+    rollupOptions: {
+      external: ['vue', 'pinia'],
+      output: {
+        globals: {
+          vue: 'Vue',
+          pinia: 'Pinia',
+        },
+      },
+    },
+  },
+});
+```
+
+### Environment Variables
+
+Production builds use `.env.production` if present:
+
+```bash
+# .env.production
+VITE_API_URL=https://api.gramercy.cloud
+VITE_ENVIRONMENT=production
+```
+
+Access in code:
+
+```javascript
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+## Pre-Build Checklist
+
+Before building for production:
+
+### 1. Remove Development Code
+
+```javascript
+// Remove or wrap in dev checks
+if (import.meta.env.DEV) {
+  console.log('Debug info:', data);
+}
+```
+
+### 2. Verify All Strings Are Extracted
+
+Run the string scanner to find hardcoded text:
+
+```bash
+gxdev datastore scan-strings
+```
+
+Ensure all user-facing text uses `gxp-string` directives.
+
+### 3. Check Asset References
+
+Verify all assets use `gxp-src` directives:
+
+```html
+<!-- Good -->
+<img gxp-src="hero_image" src="/dev-assets/placeholder.jpg" />
+
+<!-- Bad - hardcoded URL won't work in production -->
+<img src="/dev-assets/images/hero.jpg" />
+```
+
+### 4. Test All Layouts
+
+Test your plugin in all layout contexts:
+
+- Public layout
+- Private layout
+- System layout
+
+Use the Dev Tools layout switcher or:
+
+```javascript
+window.gxDevTools.setLayout('public');
+window.gxDevTools.setLayout('private');
+window.gxDevTools.setLayout('system');
+```
+
+### 5. Validate Manifest
+
+Ensure your `app-manifest.json` is complete:
+
+```bash
+# Check for JSON syntax errors
+cat app-manifest.json | python -m json.tool
+```
+
+## Production Considerations
+
+### Performance
+
+- **Lazy load routes** - Use dynamic imports for large components
+- **Optimize images** - Use appropriate sizes and formats
+- **Minimize dependencies** - Only import what you need
+
+```javascript
+// Lazy load heavy components
+const HeavyChart = defineAsyncComponent(() =>
+  import('./components/HeavyChart.vue')
+);
+```
+
+### Error Handling
+
+Add proper error boundaries:
+
+```vue
+<template>
+  <div v-if="error" class="error-state">
+    <p gxp-string="error_generic">Something went wrong</p>
+    <button @click="retry">Retry</button>
+  </div>
+  <div v-else>
+    <!-- Normal content -->
+  </div>
+</template>
+```
+
+### Offline Support
+
+Consider what happens when the network is unavailable:
+
+```javascript
+const store = useGxpStore();
+
+try {
+  const data = await store.apiGet('/endpoint');
+} catch (error) {
+  if (!navigator.onLine) {
+    store.updateState('offline_mode', true);
+  }
+}
+```
+
+### Accessibility
+
+Ensure your plugin is accessible:
+
+- Use semantic HTML elements
+- Add ARIA labels where needed
+- Support keyboard navigation
+- Test with screen readers
+
+```html
+<button
+  gxp-string="btn_checkin"
+  aria-label="Check in to the event"
+  @keydown.enter="handleCheckin"
+>
+  Check In
+</button>
+```
+
+## Deployment
+
+### Upload to Platform
+
+After building, upload your plugin to the GxP platform:
+
+1. Log in to the GxP admin portal
+2. Navigate to Plugins > Upload
+3. Select your `dist/` folder contents
+4. Configure plugin settings
+5. Assign to kiosks
+
+### Version Management
+
+Track your plugin versions:
+
+```json
+// package.json
+{
+  "name": "my-plugin",
+  "version": "1.2.0"
+}
+```
+
+Use semantic versioning:
+- **MAJOR** - Breaking changes
+- **MINOR** - New features (backward compatible)
+- **PATCH** - Bug fixes
+
+### Testing in Production
+
+Use the browser extensions to test your plugin on production kiosks:
+
+```bash
+# Build extensions for distribution
+gxdev ext:build
+```
+
+This creates installable extension packages for Chrome and Firefox.
+
+## Troubleshooting Builds
+
+### Build Fails with Import Errors
+
+Check that all imports use the correct aliases:
+
+```javascript
+// Correct
+import { useGxpStore } from '@gx-runtime/stores/gxpPortalConfigStore';
+
+// Wrong - path won't resolve in production
+import { useGxpStore } from '../../node_modules/@gramercytech/gx-devtools/runtime/stores/gxpPortalConfigStore';
+```
+
+### CSS Not Loading
+
+Ensure styles are properly scoped or imported:
+
+```vue
+<style scoped>
+/* Scoped styles are extracted correctly */
+.my-component {
+  color: blue;
+}
+</style>
+```
+
+### Bundle Too Large
+
+Analyze your bundle:
+
+```bash
+# Add to package.json scripts
+"analyze": "vite build --mode analyze"
+```
+
+Check for:
+- Unused dependencies
+- Large libraries that could be lazy-loaded
+- Duplicate code
+
+### Assets Not Found
+
+Production assets come from the platform. Ensure you're using directives:
+
+```html
+<!-- Platform provides the actual URL -->
+<img gxp-src="logo" src="/placeholder.jpg" />
+```
+
+The `src` attribute is only used during development as a fallback.

package/docs/dev-tools.md

@@ -0,0 +1,291 @@
+---
+sidebar_position: 5
+title: Dev Tools
+description: In-browser debugging tools and browser extensions for plugin development
+---
+
+# Dev Tools
+
+The GxP Toolkit includes powerful debugging tools to help you develop and test your plugins.
+
+## In-Browser Dev Tools
+
+Press `Ctrl+Shift+D` (or `Cmd+Shift+D` on Mac) to toggle the in-browser development tools.
+
+### Features
+
+#### Store Inspector
+
+View and edit all store state in real-time:
+
+- **pluginVars** - Settings from your manifest
+- **stringsList** - Translatable strings
+- **assetList** - Asset URLs
+- **triggerState** - Runtime state
+
+**Interactive features:**
+- Hover over keys to highlight matching elements on the page
+- Double-click values to edit them in real-time
+- Changes are reflected immediately in your plugin
+
+#### Layout Switcher
+
+Toggle between different layout contexts:
+
+- **Public** - Public-facing layout (unauthenticated users)
+- **Private** - Authenticated user layout
+- **System** - System/admin layout
+
+This simulates how your plugin appears in different platform contexts.
+
+#### Socket Simulator
+
+Send test socket events to your plugin:
+
+1. Select an event from the dropdown
+2. Modify the JSON payload if needed
+3. Click "Send" to emit the event
+
+Your plugin receives the event as if it came from the real platform.
+
+#### Mock Data Editor
+
+Edit platform-provided mock data:
+
+- **Theme colors** - Primary, secondary, background colors
+- **Navigation** - Mock router state
+- **Permissions** - Toggle permission flags
+- **Dependencies** - Configure mock dependencies
+
+### Console API
+
+Access dev tools programmatically from the browser console:
+
+```javascript
+// Open/close dev tools
+window.gxDevTools.open()
+window.gxDevTools.close()
+window.gxDevTools.toggle()
+
+// Access the store directly
+const store = window.gxDevTools.store()
+console.log(store.stringsList)
+store.updateState('test_value', 123)
+
+// Change layout
+window.gxDevTools.setLayout('private')
+window.gxDevTools.setLayout('public')
+window.gxDevTools.setLayout('system')
+
+// Get current layout
+const layout = window.gxDevTools.getLayout()
+console.log(layout) // 'private'
+```
+
+## Browser Extensions
+
+The toolkit includes browser extensions for Chrome and Firefox that provide advanced inspection capabilities.
+
+### Installation
+
+#### Chrome
+
+```bash
+# Launch Chrome with extension auto-loaded
+gxdev dev --chrome
+
+# Or install manually:
+# 1. Go to chrome://extensions
+# 2. Enable "Developer mode"
+# 3. Click "Load unpacked"
+# 4. Select browser-extensions/chrome/
+```
+
+#### Firefox
+
+```bash
+# Launch Firefox with extension auto-loaded
+gxdev dev --firefox
+
+# Or install manually:
+# 1. Go to about:debugging
+# 2. Click "This Firefox"
+# 3. Click "Load Temporary Add-on"
+# 4. Select browser-extensions/firefox/manifest.json
+```
+
+### Extension Features
+
+#### Element Selection
+
+Click the selection tool in the DevTools panel, then click any element on the page to inspect it.
+
+#### Visual Highlighting
+
+- **Hover** - Orange dashed border shows element boundaries
+- **Selected** - Cyan pulsing glow indicates the selected element
+
+#### Smart Labels
+
+Elements are labeled with their component context:
+
+```
+ComponentName::element::gxp-string-key
+```
+
+Examples:
+- `DemoPage::h1::welcome_title`
+- `CheckInForm::button::btn_submit`
+- `Header::img::logo`
+
+#### String Extraction
+
+Identify hardcoded strings and convert them to `gxp-string` directives:
+
+1. Select an element with hardcoded text
+2. Click "Extract to gxp-string"
+3. Enter a key name
+4. The extension suggests the code change
+
+#### Component Inspector
+
+View Vue component details:
+
+- Component name and hierarchy
+- Props and their values
+- Reactive data
+- Computed properties
+
+### Reloading Extensions
+
+After modifying extension code in `browser-extensions/`:
+
+**Chrome:**
+1. Go to `chrome://extensions`
+2. Find "GxP Inspector"
+3. Click the refresh icon
+
+**Firefox:**
+1. Go to `about:debugging`
+2. Find "GxP Inspector"
+3. Click "Reload"
+
+## CLI Dev Commands
+
+### Datastore Commands
+
+```bash
+# List all store variables
+gxdev datastore list
+
+# Add a new variable interactively
+gxdev datastore add
+
+# Scan components for hardcoded strings
+gxdev datastore scan-strings
+```
+
+The scan-strings command finds text that should be extracted to your manifest:
+
+```bash
+$ gxdev datastore scan-strings
+
+Scanning components for hardcoded strings...
+
+src/CheckInForm.vue:
+  Line 12: "Welcome to the event"  -> Suggest: welcome_title
+  Line 24: "Check In"              -> Suggest: btn_checkin
+
+src/ErrorPage.vue:
+  Line 8:  "Something went wrong"  -> Suggest: error_generic
+
+Found 3 hardcoded strings in 2 files.
+```
+
+### Socket Commands
+
+```bash
+# List available socket events
+gxdev socket list
+
+# Send a test event
+gxdev socket send --event SessionUpdated
+
+# Send with custom data
+gxdev socket send --event AttendeeCheckedIn --data '{"id": 123}'
+```
+
+### Asset Commands
+
+```bash
+# List development assets
+gxdev assets list
+
+# Initialize asset directories
+gxdev assets init
+
+# Generate placeholder images
+gxdev assets generate --size 400x300 --name hero
+gxdev assets generate --size 200x200 --name avatar --format png
+```
+
+## Debugging Tips
+
+### 1. Use Vue DevTools
+
+Install the [Vue DevTools browser extension](https://devtools.vuejs.org/) for component inspection:
+
+- Component tree visualization
+- State inspection
+- Event tracking
+- Performance profiling
+
+### 2. Enable Source Maps
+
+Source maps are enabled by default in development. Check your browser's Sources panel to debug original source files.
+
+### 3. Console Logging
+
+Use the store's console helpers:
+
+```javascript
+const store = useGxpStore();
+
+// Log current state
+console.log('Settings:', store.pluginVars);
+console.log('Strings:', store.stringsList);
+console.log('State:', store.triggerState);
+```
+
+### 4. Network Tab
+
+Monitor API calls in your browser's Network tab. The store's API client logs requests in development mode.
+
+### 5. Hot Reload Issues
+
+If hot reload stops working:
+
+1. Check the terminal for Vite errors
+2. Look for syntax errors in your components
+3. Try a manual page refresh
+4. Restart the dev server if needed
+
+## Troubleshooting
+
+### Dev tools not opening
+
+- Ensure you're on the development server (localhost:3060)
+- Check browser console for JavaScript errors
+- Try refreshing the page
+
+### Extension not highlighting elements
+
+- Reload the extension after code changes
+- Check console for `[GxP Inspector] Loaded` message
+- Ensure you're inspecting the correct tab
+
+### Store changes not reflecting
+
+- Verify your manifest syntax is valid JSON
+- Check for typos in key names
+- Ensure you're using the correct getter method