@gxp-dev/tools 2.0.5 → 2.0.7

package/docs/DOCUSAURUS_IMPORT.md

@@ -1,378 +0,0 @@
-# Importing GxP Toolkit Docs into Docusaurus
-
-This guide shows how to configure your platform's Docusaurus site to automatically import documentation from this repository.
-
-## Option 1: Remote Content Plugin (Recommended)
-
-Use `docusaurus-plugin-remote-content` to fetch docs at build time.
-
-### Installation
-
-```bash
-npm install docusaurus-plugin-remote-content
-```
-
-### Configuration
-
-Add to your `docusaurus.config.js`:
-
-```javascript
-module.exports = {
-  // ... other config
-
-  plugins: [
-    [
-      'docusaurus-plugin-remote-content',
-      {
-        // Unique name for this remote source
-        name: 'gx-devtools-docs',
-
-        // GitHub raw content URL for the docs folder
-        sourceBaseUrl:
-          'https://raw.githubusercontent.com/gramercytech/gx-devtools/develop/docs/',
-
-        // Where to output the fetched docs
-        outDir: 'docs/gx-devtools',
-
-        // List of documents to fetch
-        documents: [
-          'index.md',
-          'getting-started.md',
-          'app-manifest.md',
-          'gxp-store.md',
-          'dev-tools.md',
-          'building-for-platform.md',
-        ],
-
-        // Fetch category config too
-        // Note: _category_.json needs special handling (see below)
-      },
-    ],
-  ],
-};
-```
-
-### Fetching _category_.json
-
-The category file needs to be fetched separately since it's not markdown:
-
-```javascript
-module.exports = {
-  plugins: [
-    // Markdown docs
-    [
-      'docusaurus-plugin-remote-content',
-      {
-        name: 'gx-devtools-docs',
-        sourceBaseUrl:
-          'https://raw.githubusercontent.com/gramercytech/gx-devtools/main/docs/',
-        outDir: 'docs/gx-devtools',
-        documents: [
-          'index.md',
-          'getting-started.md',
-          'app-manifest.md',
-          'gxp-store.md',
-          'dev-tools.md',
-          'building-for-platform.md',
-        ],
-        // Ensure content is returned as string (plugin expects {content: string} object)
-        modifyContent: (filename, content) => {
-          return {
-            content: typeof content === "string" ? content : String(content),
-          }
-        },
-      },
-    ],
-    // Category config (JSON)
-    [
-      'docusaurus-plugin-remote-content',
-      {
-        name: 'gx-devtools-category',
-        sourceBaseUrl:
-          'https://raw.githubusercontent.com/gramercytech/gx-devtools/main/docs/',
-        outDir: 'docs/gx-devtools',
-        documents: ['_category_.json'],
-        // JSON files need to be stringified before writing (plugin expects {content: string} object)
-        modifyContent: (filename, content) => {
-          return {
-            content:
-              typeof content === "string"
-                ? content
-                : JSON.stringify(content, null, 2),
-          }
-        },
-      },
-    ],
-  ],
-};
-```
-
-### Dynamic Document List (Advanced)
-
-Fetch the document list dynamically from GitHub API:
-
-```javascript
-const { Octokit } = require('@octokit/rest');
-
-module.exports = {
-  plugins: [
-    [
-      'docusaurus-plugin-remote-content',
-      {
-        name: 'gx-devtools-docs',
-        sourceBaseUrl:
-          'https://raw.githubusercontent.com/gramercytech/gx-devtools/main/docs/',
-        outDir: 'docs/gx-devtools',
-
-        // Dynamically fetch file list
-        documents: async () => {
-          const octokit = new Octokit();
-          const { data } = await octokit.repos.getContent({
-            owner: 'gramercytech',
-            repo: 'gx-devtools',
-            path: 'docs',
-          });
-
-          return data
-            .filter((file) => file.name.endsWith('.md'))
-            .map((file) => file.name);
-        },
-      },
-    ],
-  ],
-};
-```
-
-## Option 2: Git Submodule
-
-Add gx-devtools as a git submodule and reference its docs directly.
-
-### Setup
-
-```bash
-# Add submodule
-git submodule add https://github.com/gramercytech/gx-devtools.git packages/gx-devtools
-
-# Update .gitmodules
-git submodule update --init --recursive
-```
-
-### Configuration
-
-```javascript
-// docusaurus.config.js
-module.exports = {
-  presets: [
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          // Include gx-devtools docs
-          include: ['**/*.md', '../packages/gx-devtools/docs/**/*.md'],
-        },
-      },
-    ],
-  ],
-};
-```
-
-### CI/CD Update
-
-Add to your build script:
-
-```bash
-git submodule update --remote --merge
-```
-
-## Option 3: npm Package Docs
-
-Since gx-devtools is an npm package, reference docs from node_modules.
-
-### Configuration
-
-```javascript
-// docusaurus.config.js
-const path = require('path');
-
-module.exports = {
-  plugins: [
-    [
-      '@docusaurus/plugin-content-docs',
-      {
-        id: 'gx-devtools',
-        path: path.resolve(
-          __dirname,
-          'node_modules/@gramercytech/gx-devtools/docs'
-        ),
-        routeBasePath: 'gx-devtools',
-        sidebarPath: require.resolve('./sidebars-gx-devtools.js'),
-      },
-    ],
-  ],
-};
-```
-
-### Sidebar Config
-
-Create `sidebars-gx-devtools.js`:
-
-```javascript
-module.exports = {
-  gxToolkitSidebar: [
-    'index',
-    'getting-started',
-    'app-manifest',
-    'gxp-store',
-    'dev-tools',
-    'building-for-platform',
-  ],
-};
-```
-
-## Sidebar Integration
-
-To include gx-devtools docs in your main sidebar:
-
-```javascript
-// sidebars.js
-module.exports = {
-  docs: [
-    'intro',
-    'quickstart',
-    // ... your other docs
-
-    // Link to gx-devtools section
-    {
-      type: 'category',
-      label: 'GxP Toolkit',
-      link: {
-        type: 'doc',
-        id: 'gx-devtools/index',
-      },
-      items: [
-        'gx-devtools/getting-started',
-        'gx-devtools/app-manifest',
-        'gx-devtools/gxp-store',
-        'gx-devtools/dev-tools',
-        'gx-devtools/building-for-platform',
-      ],
-    },
-  ],
-};
-```
-
-## Customizing Imported Docs
-
-### Modify Content During Fetch
-
-```javascript
-[
-  'docusaurus-plugin-remote-content',
-  {
-    name: 'gx-devtools-docs',
-    sourceBaseUrl: '...',
-    outDir: 'docs/gx-devtools',
-    documents: ['getting-started.md'],
-
-    // Modify content before writing
-    modifyContent: (filename, content) => {
-      // Add custom header
-      if (filename === 'index.md') {
-        return {
-          filename,
-          content: content.replace(
-            '---',
-            '---\ncustom_edit_url: https://github.com/gramercytech/gx-devtools/edit/main/docs/index.md'
-          ),
-        };
-      }
-      return undefined; // No modification
-    },
-  },
-];
-```
-
-### Override Specific Pages
-
-Create local overrides that take precedence:
-
-```
-docs/
-├── gx-devtools/           # Remote content lands here
-│   ├── index.md          # From remote
-│   └── getting-started.md # From remote
-└── gx-devtools-overrides/
-    └── getting-started.md # Your custom version
-```
-
-Configure path priority in Docusaurus.
-
-## Adding/Removing Pages
-
-To add new pages to gx-devtools docs:
-
-1. Create the `.md` file in `/docs/` in this repo
-2. Add Docusaurus frontmatter (sidebar_position, title, etc.)
-3. Add the filename to the `documents` array in your platform's config
-4. Rebuild your platform docs
-
-To remove a page:
-
-1. Remove from the `documents` array
-2. Delete from your `outDir` if using CLI sync mode
-3. Rebuild
-
-## Triggering Rebuilds
-
-### GitHub Actions (Recommended)
-
-Set up a webhook to rebuild platform docs when gx-devtools changes:
-
-```yaml
-# .github/workflows/docs-update.yml (in gx-devtools repo)
-name: Notify Platform Docs
-
-on:
-  push:
-    paths:
-      - 'docs/**'
-
-jobs:
-  notify:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Trigger platform docs rebuild
-        run: |
-          curl -X POST \
-            -H "Authorization: token ${{ secrets.PLATFORM_DOCS_TOKEN }}" \
-            -H "Accept: application/vnd.github.v3+json" \
-            https://api.github.com/repos/gramercytech/platform-docs/dispatches \
-            -d '{"event_type": "gx-devtools-docs-updated"}'
-```
-
-### Manual Rebuild
-
-```bash
-# Clear cached remote content
-npx docusaurus clear-remote-gx-devtools-docs
-
-# Rebuild
-npm run build
-```
-
-## Versioning
-
-If you need versioned docs:
-
-```javascript
-[
-  'docusaurus-plugin-remote-content',
-  {
-    name: 'gx-devtools-docs-v1',
-    sourceBaseUrl:
-      'https://raw.githubusercontent.com/gramercytech/gx-devtools/v1.0.0/docs/',
-    outDir: 'versioned_docs/version-1.0/gx-devtools',
-    documents: ['index.md', '...'],
-  },
-];
-```

package/docs/_category_.json

@@ -1,8 +0,0 @@
-{
-  "label": "GxP Toolkit",
-  "position": 10,
-  "link": {
-    "type": "generated-index",
-    "description": "Documentation for the GxP Dev Toolkit - build plugins for the GxP kiosk platform."
-  }
-}

package/docs/app-manifest.md

@@ -1,272 +0,0 @@
----
-sidebar_position: 3
-title: App Manifest
-description: Configure your plugin with settings, strings, assets, and more
----
-
-# App Manifest
-
-The `app-manifest.json` file is the central configuration for your GxP plugin. It defines settings, translatable strings, assets, and runtime state that the platform injects into your plugin.
-
-## File Location
-
-The manifest file should be in your project root:
-
-```
-my-plugin/
-├── app-manifest.json    # <-- Here
-├── src/
-└── ...
-```
-
-## Basic Structure
-
-```json
-{
-  "settings": {},
-  "strings": {},
-  "assets": {},
-  "triggerState": {},
-  "dependencies": [],
-  "permissions": []
-}
-```
-
-## Configuration Sections
-
-### Settings (`pluginVars`)
-
-Define configurable settings that administrators can customize per deployment:
-
-```json
-{
-  "settings": {
-    "primary_color": "#FFD600",
-    "background_color": "#ffffff",
-    "company_name": "Acme Corp",
-    "max_items": 10,
-    "enable_animations": true
-  }
-}
-```
-
-Access in your component:
-
-```javascript
-const store = useGxpStore();
-
-// Get a setting with fallback
-const color = store.getSetting('primary_color', '#000000');
-
-// Check if setting exists
-if (store.pluginVars.enable_animations) {
-  // ...
-}
-```
-
-Use in templates with the `gxp-settings` modifier:
-
-```html
-<span gxp-string="company_name" gxp-settings>Default Company</span>
-```
-
-### Strings (`stringsList`)
-
-Define translatable text content:
-
-```json
-{
-  "strings": {
-    "default": {
-      "welcome_title": "Welcome to the Event",
-      "welcome_subtitle": "Please check in below",
-      "button_checkin": "Check In",
-      "button_cancel": "Cancel",
-      "error_not_found": "Registration not found"
-    }
-  }
-}
-```
-
-Use in templates with the `gxp-string` directive:
-
-```html
-<h1 gxp-string="welcome_title">Default Welcome</h1>
-<button gxp-string="button_checkin">Check In</button>
-```
-
-Access programmatically:
-
-```javascript
-const store = useGxpStore();
-const title = store.getString('welcome_title', 'Default Title');
-```
-
-:::tip Hot Reload
-Changes to strings in `app-manifest.json` are hot-reloaded during development. No page refresh needed!
-:::
-
-### Assets (`assetList`)
-
-Define asset URLs (images, documents, etc.):
-
-```json
-{
-  "assets": {
-    "hero_image": "/dev-assets/images/hero.jpg",
-    "logo": "/dev-assets/images/logo.png",
-    "background": "/dev-assets/images/bg-pattern.svg",
-    "welcome_video": "/dev-assets/videos/intro.mp4"
-  }
-}
-```
-
-Use in templates with the `gxp-src` directive:
-
-```html
-<img gxp-src="hero_image" src="/dev-assets/placeholder.jpg" alt="Hero" />
-<img gxp-src="logo" src="/dev-assets/placeholder.jpg" alt="Logo" />
-```
-
-Access programmatically:
-
-```javascript
-const store = useGxpStore();
-const heroUrl = store.getAsset('hero_image', '/fallback.jpg');
-```
-
-### Trigger State (`triggerState`)
-
-Define dynamic runtime state that can change during plugin execution:
-
-```json
-{
-  "triggerState": {
-    "is_active": true,
-    "current_step": 1,
-    "checked_in_count": 0,
-    "last_scan_result": null
-  }
-}
-```
-
-Use in templates with the `gxp-state` modifier:
-
-```html
-<span gxp-string="current_step" gxp-state>1</span>
-<img gxp-src="dynamic_badge" gxp-state src="/placeholder.jpg" />
-```
-
-Update programmatically:
-
-```javascript
-const store = useGxpStore();
-
-// Update state
-store.updateState('current_step', 2);
-store.updateState('checked_in_count', store.triggerState.checked_in_count + 1);
-
-// Read state
-const step = store.getState('current_step', 1);
-```
-
-### Dependencies
-
-Define external services or plugins this plugin depends on:
-
-```json
-{
-  "dependencies": [
-    {
-      "id": "badge-printer",
-      "type": "hardware",
-      "required": true
-    },
-    {
-      "id": "registration-api",
-      "type": "api",
-      "required": true
-    }
-  ]
-}
-```
-
-### Permissions
-
-Define permissions required by the plugin:
-
-```json
-{
-  "permissions": [
-    "camera",
-    "bluetooth",
-    "notifications"
-  ]
-}
-```
-
-Check permissions in code:
-
-```javascript
-const store = useGxpStore();
-
-if (store.hasPermission('camera')) {
-  // Enable camera features
-}
-```
-
-## Complete Example
-
-```json
-{
-  "settings": {
-    "primary_color": "#FFD600",
-    "secondary_color": "#1976D2",
-    "company_name": "TechConf 2024",
-    "check_in_timeout": 30,
-    "enable_badge_printing": true
-  },
-  "strings": {
-    "default": {
-      "welcome_title": "Welcome to TechConf 2024",
-      "welcome_subtitle": "Scan your QR code to check in",
-      "btn_manual_entry": "Enter Code Manually",
-      "btn_help": "Need Help?",
-      "success_message": "You're all set!",
-      "error_invalid_code": "Invalid code. Please try again.",
-      "error_already_checked_in": "You've already checked in."
-    }
-  },
-  "assets": {
-    "logo": "/dev-assets/images/techconf-logo.png",
-    "hero_background": "/dev-assets/images/hero-bg.jpg",
-    "success_animation": "/dev-assets/animations/success.json"
-  },
-  "triggerState": {
-    "is_scanning": false,
-    "current_attendee": null,
-    "badge_printing": false
-  },
-  "dependencies": [],
-  "permissions": ["camera"]
-}
-```
-
-## Directive Reference
-
-| Directive | Modifier | Source | Example |
-|-----------|----------|--------|---------|
-| `gxp-string` | (none) | `stringsList` | `<h1 gxp-string="title">Default</h1>` |
-| `gxp-string` | `gxp-settings` | `pluginVars` | `<span gxp-string="company" gxp-settings>Acme</span>` |
-| `gxp-string` | `gxp-assets` | `assetList` | `<span gxp-string="logo_url" gxp-assets>/logo.png</span>` |
-| `gxp-string` | `gxp-state` | `triggerState` | `<span gxp-string="count" gxp-state>0</span>` |
-| `gxp-src` | (none) | `assetList` | `<img gxp-src="hero" src="/placeholder.jpg" />` |
-| `gxp-src` | `gxp-state` | `triggerState` | `<img gxp-src="badge" gxp-state src="/placeholder.jpg" />` |
-
-## Best Practices
-
-1. **Use descriptive keys** - `welcome_title` is better than `title1`
-2. **Provide defaults** - Always include fallback text in your templates
-3. **Group related strings** - Keep related strings together for easier management
-4. **Use dev-assets for development** - Put placeholder images in `dev-assets/images/`
-5. **Keep settings minimal** - Only expose settings that need admin configuration