js-kompo-utils 1.0.0

package/docs/tutorials.md

@@ -0,0 +1,247 @@
+# Tutorial System
+
+## Overview
+
+The tutorial system provides guided walkthroughs for users. Tutorials are defined as JSON files, processed server-side by PHP (translations, conditions, user variables), and rendered client-side by the TutorialEngine.
+
+## Architecture
+
+```
+resources/tutorials/dashboard-view.json     ← You author this (pure data)
+         ↓
+PHP: TutorialProcessor                      ← Translates, filters, replaces variables
+         ↓
+GET /api/tutorials/dashboard-view           ← Serves processed JSON
+         ↓
+JS: TutorialEngine                          ← Renders overlay, bubble, cursor, highlights
+```
+
+### Key components
+
+| Component | Role |
+|-----------|------|
+| **TutorialEngine** (JS) | Orchestrates modules: Overlay, Bubble, Cursor, Highlight, etc. |
+| **TutorialProcessor** (PHP) | Loads JSON, translates strings, evaluates conditions, replaces `{{variables}}` |
+| **TutorialConditionEvaluator** (PHP) | Safe expression parser for `showIf` conditions |
+| **HasTutorial** (PHP plugin) | Auto-detects tutorials for Kompo components, triggers on first visit |
+| **TutorialStepBuilder** (PHP + JS) | Dev-only visual editor for editing steps live |
+
+## Creating a Tutorial
+
+### 1. Create the JSON file
+
+Place it in `resources/tutorials/{component-slug}.json`. The slug matches the Kompo component name (e.g., `DashboardView` → `dashboard-view`).
+
+```json
+{
+    "steps": [
+        {
+            "html": "tutorial.welcome"
+        },
+        {
+            "html": "tutorial.click-here",
+            "highlight": { "groups": [{ "elements": ["#my-button"] }] },
+            "position": "right"
+        },
+        {
+            "html": "tutorial.fill-form",
+            "highlight": { "groups": [{ "elements": [".form-field", ".submit-btn"] }] },
+            "cursor": {
+                "from": ".form-field",
+                "to": ".submit-btn",
+                "click": true,
+                "duration": 1.5
+            }
+        }
+    ]
+}
+```
+
+### 2. Add translations
+
+In your translation files (`resources/lang/en/tutorial.php`):
+
+```php
+return [
+    'welcome' => 'Welcome, {{user_first_name}}! Let me show you around.',
+    'click-here' => 'Click this button to get started.',
+    'fill-form' => 'Fill in the form and hit submit.',
+];
+```
+
+The PHP processor translates keys and replaces `{{user_first_name}}`, `{{user_last_name}}`, `{{user_name}}` automatically.
+
+### 3. That's it
+
+The `HasTutorial` plugin auto-detects the JSON file based on the component slug and starts the tutorial on first visit. A replay button in the navbar lets users re-watch it anytime.
+
+## Step Configuration
+
+Each step supports these properties:
+
+```json
+{
+    "html": "translation.key",
+
+    "position": "left | right | top | bottom",
+    "align": "left | center | right",
+    "overlay": true,
+
+    "highlight": {
+        "groups": [{ "elements": [".selector1", ".selector2"] }],
+        "padding": 8,
+        "borderRadius": 8
+    },
+
+    "cursor": {
+        "from": ".start-element",
+        "to": ".end-element",
+        "click": true,
+        "duration": 1.5,
+        "loop": true
+    },
+
+    "hover": ".element-to-force-hover",
+
+    "scrollTo": ".element-to-scroll-into-view",
+    "scrollInside": { "selector": ".container", "by": 200, "duration": 1 },
+
+    "options": [
+        { "label": "tutorial.option-a", "goToStep": 4 },
+        { "label": "tutorial.option-b", "done": true },
+        { "label": "tutorial.option-c", "redirect": "/other-page" }
+    ],
+
+    "autoNext": 3,
+    "advance": "click | afterAnimation",
+    "silentClick": ".element-to-auto-click",
+    "showBack": true,
+    "chatMode": true,
+
+    "showIf": "permission:ManageTeam && !setting:hide_tutorial",
+
+    "redirect": "/next-page"
+}
+```
+
+## Triggering Tutorials
+
+### Automatic (first visit)
+
+The `HasTutorial` plugin handles this. If `resources/tutorials/{component-slug}.json` exists, the tutorial starts on first visit and is marked as viewed.
+
+### Button click (replay)
+
+```php
+// Uses 'default' — auto-resolves to current page's tutorial
+_Button('Help')->initTutorial();
+
+// Or specify a tutorial explicitly
+_Button('Start Tour')->initTutorial('campaign-settings');
+
+// Start at a specific step
+_Button('Show Step 3')->initTutorial('campaign-settings', stepNumber: 2);
+```
+
+### On page load (cross-page redirect)
+
+Use `_Tutorial()` in a component's `render()` method:
+
+```php
+function render()
+{
+    return _Rows(
+        _Tutorial('onboarding-step-2'),
+        // ... rest of component
+    );
+}
+```
+
+This supports cross-page chaining — when a tutorial redirects to another page with `?tutorial=name&fromStep=N`, the `_Tutorial()` helper picks it up and starts automatically.
+
+## Conditional Steps
+
+Use `showIf` to conditionally show steps based on user permissions, settings, or DOM elements:
+
+```json
+{ "showIf": "permission:ManageTeam" }
+{ "showIf": "permission:EditCampaign && !setting:onboarding_done" }
+{ "showIf": "(role:admin || role:manager) && permission:ViewFinances" }
+{ "showIf": "selector:.optional-feature-panel" }
+```
+
+**Built-in condition types:**
+- `permission:X` — checks `user->hasPermission(X)`
+- `setting:X` — checks `user->getSettingValue(X)`
+- `role:X` — checks `user->hasRole(X)`
+- `selector:X` — checks if DOM element exists (evaluated client-side)
+
+**Custom conditions** — register in a service provider:
+
+```php
+TutorialConditionEvaluator::register('hasActiveSubscription',
+    fn() => auth()->user()->subscription?->isActive() ?? false
+);
+```
+
+Then use: `"showIf": "hasActiveSubscription && permission:ManageBilling"`
+
+## Cross-Page Tutorials
+
+When a step needs to redirect to another page and continue:
+
+```json
+{
+    "html": "tutorial.go-to-settings",
+    "options": [
+        {
+            "label": "tutorial.lets-go",
+            "redirect": "/campaign/settings",
+            "startTutorial": "campaign-settings"
+        }
+    ]
+}
+```
+
+The target page should have `_Tutorial('campaign-settings')` in its render method to pick up the redirect.
+
+## Dev Mode: Step Builder
+
+In debug mode (`APP_DEBUG=true`):
+- A step builder panel is available in the navbar
+- Clicking the replay button also opens the visual editor
+- Edit step properties, pick elements, preview live changes
+- Copy the JSON output to update your tutorial file
+
+## File Structure
+
+```
+js-kompo-utils/tutorials/
+├── TutorialEngine.js          # Main orchestrator
+├── TutorialConfig.js          # Defaults + config
+├── tutorial.scss              # All tutorial styles
+├── modules/
+│   ├── Avatar.js              # Container + avatar image
+│   ├── Overlay.js             # Full-screen overlay
+│   ├── Bubble.js              # Speech bubble + positioning
+│   ├── Typewriter.js          # Character-by-character text
+│   ├── Cursor.js              # Animated cursor + click pulse
+│   ├── Highlight.js           # SVG cutout overlay
+│   ├── HoverForcer.js         # Force :hover styles
+│   ├── Scroll.js              # Scroll helpers
+│   ├── Options.js             # Choice buttons
+│   ├── AutoNext.js            # Timed progress bar
+│   └── Mobile.js              # Mobile detection + tab handling
+├── utils/
+│   ├── selectors.js           # CSS selector utilities
+│   ├── svg.js                 # SVG element helpers
+│   └── stability.js           # Element position polling
+└── step-builder/              # Dev-only visual editor
+    ├── step-builder-bridge.js
+    └── utils/
+
+utils/src/Tutorials/
+├── TutorialProcessor.php      # JSON loading + translation + conditions
+├── TutorialConditionEvaluator.php  # Safe expression parser
+└── TutorialStepBuilder.php    # Kompo Form for visual editor
+```

package/docs/usage.md

@@ -0,0 +1,128 @@
+# js-kompo-utils - Usage Guide
+
+## Quick Start
+
+In your Laravel app's `app.js`:
+
+```javascript
+import { defaultConfig, KompoJsInitializer } from 'js-kompo-utils';
+
+const config = defaultConfig
+    .bootstrap(() => require('./bootstrap'));
+
+new KompoJsInitializer(config, window).initialize();
+```
+
+This gives you: jQuery, Vue + vue-kompo, CKEditor, Google Maps, QR code reader, all default components, window utilities, and animations.
+
+## What's included by default
+
+| Feature | Default | Toggle off |
+|---------|---------|------------|
+| jQuery | on | `.withoutJquery()` |
+| CKEditor | on | `.withoutCkEditor()` |
+| Google Maps | on | `.withoutKompoMaps()` |
+| Tutorial Engine | on | `.withoutTutorialEngine()` |
+| QR Code Reader | on (Vue plugin) | - |
+| Default components | all `./components/*.vue` | `.excludeComponent('Name')` |
+| Window utils | input + loading functions | - |
+| Animations | count-up, magic-poof | - |
+
+## Adding and removing components
+
+```javascript
+// Add an app-specific component
+config.addComponent('MyComponent', require('./components/MyComponent.vue').default);
+
+// Add multiple
+config.addComponents({
+    'CompA': require('./components/CompA.vue').default,
+    'CompB': require('./components/CompB.vue').default,
+});
+
+// Remove a default component you don't need
+config.excludeComponent('VlApexChart');
+config.excludeComponents(['VlCKEditorTemplate', 'VlCKEditorWithVars']);
+```
+
+## Adding Vue plugins
+
+```javascript
+import SomePlugin from 'some-vue-plugin';
+
+config.addVuePlugin(SomePlugin);
+```
+
+## Adding files to import
+
+Pass callbacks — webpack resolves the path at build time:
+
+```javascript
+config.addFilesToImport([
+    () => require('./my-custom-script.js'),
+    () => require('./another-script.js'),
+]);
+```
+
+## Window utilities
+
+```javascript
+// Add individual functions to window
+config.addWindowUtilsItem('myHelper', () => { /* ... */ });
+
+// Merge an object of functions
+config.mergeWindowUtils({
+    helperA: () => { /* ... */ },
+    helperB: () => { /* ... */ },
+});
+
+// Add a decorator that receives window and does custom setup
+config.addWindowDecorator((window) => {
+    // custom window setup
+});
+```
+
+## Lifecycle hooks
+
+Hook into any initialization step with before/after callbacks:
+
+```javascript
+config.addAfterStepCallback('bootstrapExecution', () => {
+    // runs after bootstrap, e.g. add axios interceptors
+    window.axios.interceptors.request.use(config => {
+        config.headers['X-Custom'] = 'value';
+        return config;
+    });
+});
+
+config.addBeforeStepCallback('instanceApp', () => {
+    // runs right before Vue mounts
+});
+```
+
+**Available step names:** `bootstrapExecution`, `requireFilesToImport`, `bootJqueryIfRequired`, `bootVue`, `decorateWindow`, `bootCkEditorIfRequired`, `bootMapsIfRequired`, `instanceApp`
+
+## Changing the mount selector
+
+Default is `#app` (matches kompo's `vue_app_id` config). Override if needed:
+
+```javascript
+config.setAppSelector('#my-app');
+```
+
+## Starting from scratch
+
+If `defaultConfig` includes too much, build your own:
+
+```javascript
+import { KompoJsConfigBuilder, KompoJsInitializer } from 'js-kompo-utils';
+
+const config = new KompoJsConfigBuilder()
+    .bootstrap(() => require('./bootstrap'))
+    .withJquery()
+    .withoutCkEditor()
+    .withoutKompoMaps()
+    .addComponent('MyOnly', require('./components/MyOnly.vue').default);
+
+new KompoJsInitializer(config, window).initialize();
+```

package/functions/index.js

@@ -0,0 +1,7 @@
+import inputFunctions from './inputs.js';
+import loadingFunctions from './loading.js';
+
+export default {
+    ...inputFunctions,
+    ...loadingFunctions
+};

package/functions/inputs.js

@@ -0,0 +1,64 @@
+export function getYesNoValue(id)
+{
+	const group = $('#' + id);
+
+	const rawValue = group.find('.selected').find('*[data-value]').data('value');
+	
+	if (rawValue == undefined) {
+		return null;
+	}
+
+	const value = rawValue == 'yes' ? 1 : 0;
+
+	return value;
+}
+
+export function getToggle(name)
+{
+	return $('input[type=checkbox][name="' + name + '"]');
+}
+
+export function getToggleValue(name)
+{
+	const toggleCheckbox = getToggle(name);
+    const checked = toggleCheckbox.attr('aria-checked') == "true";
+
+	return checked ? 1 : 0;
+}
+
+export function toggleYesNo(name) {
+	const groupId = 'temp_' + name;
+	const toggleName = name + '_toggle';
+
+	const groupValue = getYesNoValue(groupId);
+	const toggleValue = getToggleValue(toggleName);
+
+	// This want to fix the first "no" select when the default is null
+	if(groupValue == null) {
+		$('#' + name + '-off-input').hide();
+		$('#' + name + '-on-input').hide();
+
+		return;
+	}
+
+	if (groupValue != toggleValue) {
+		console.log(getToggle(toggleName));
+		getToggle(toggleName).each(function(key, toggle) {
+			const evt = new Event( 'click', { bubbles: true } );
+			toggle.nextElementSibling.dispatchEvent(evt);
+		});
+	} else if (groupValue == 1) {
+		$('#' + name + '-off-input').hide();
+		$('#' + name + '-on-input').show();
+	} else if(groupValue == 0) {
+		$('#' + name + '-off-input').show();
+		$('#' + name + '-on-input').hide();
+	}  
+}
+
+export default {
+	getYesNoValue,
+	getToggle,
+	getToggleValue,
+	toggleYesNo
+}

package/functions/loading.js

@@ -0,0 +1,20 @@
+export function setLoadingScreen()
+{
+    const loadingInnerHtml = `
+        <div class="loading-screen">
+            <i id="vl-spinner" class="icon-spinner" style="display: block;"></i>
+        </div>
+    `;
+
+    $('body').append(loadingInnerHtml);
+}
+
+export function removeLoadingScreen()
+{
+	$('.loading-screen').remove();
+}
+
+export default {
+    setLoadingScreen,
+    removeLoadingScreen
+}

package/kompo-ckeditor-1.0.17/index.js

@@ -0,0 +1,5 @@
+const files = require.context('./komponents/', true, /\.vue$/i)
+		
+files.keys().map(key => {
+	Vue.component('Vl'+key.split('/').pop().split('.')[0], files(key).default)
+})

package/kompo-ckeditor-1.0.17/komponents/CKEditor.vue

@@ -0,0 +1,36 @@
+<template>
+    <vl-form-field v-bind="$_wrapperAttributes" @labelclick="focus">
+        <ckeditor 
+            class="vlFormControl"
+            ref="content"
+            v-model="component.value" 
+            v-bind="$_attributes"
+            v-on="$_events"
+            @keydown.stop
+            @ready="onReady"
+            
+            :editor="editor" 
+            :config="editorConfig" />
+        <div 
+          v-if="mentions.length" 
+          class="mention-triggers border-t border-gray-200 p-2 flex">
+          <div 
+              v-for="(mention, index) in mentions"
+              v-html="getButtonHtml(mention)"
+              @click="activateMention(mention)"
+              />
+        </div>
+        <a v-if="customTextInsertion" 
+            @click="insertCustomText" 
+            class="cursor-pointer absolute bottom-2 right-2 text-sm" 
+            v-html="customTextInsertLabel" /> 
+    </vl-form-field>
+</template>
+
+<script>
+import CKEditor from '../mixins/CKEditor'
+
+export default {
+    mixins: [CKEditor]
+}
+</script>

package/kompo-ckeditor-1.0.17/komponents/CKEditorExtended.vue

@@ -0,0 +1,66 @@
+<template>
+    <vl-form-field v-bind="$_wrapperAttributes" @labelclick="focus">
+        <ckeditor 
+            class="vlFormControl"
+            ref="content"
+            v-model="component.value" 
+            v-bind="$_attributes"
+            v-on="$_events"
+            @keydown.stop
+            
+            :editor="editor" 
+            :config="editorConfig" />
+        <div 
+          v-if="mentions.length" 
+          class="mention-triggers border-t border-gray-200 p-2 flex">
+          <div 
+              v-for="(mention, index) in mentions"
+              :key="index"
+              v-html="getButtonHtml(mention)"
+              @click="activateMention(mention)"
+          />
+          <VlDate 
+              :vkompo="$_config('date-component')"
+              @open="onOpen"
+              @change="onChange"
+              @close="onClose"
+          />
+        </div>
+    </vl-form-field>
+</template>
+
+<script>
+import CKEditor from '../mixins/CKEditor'
+import DoesAxiosRequests from 'vue-kompo/js/form/mixins/DoesAxiosRequests'
+import EmitsEvents from 'vue-kompo/js/element/mixins/EmitsEvents'
+import HasId from 'vue-kompo/js/element/mixins/HasId'
+import HasConfig from 'vue-kompo/js/element/mixins/HasConfig'
+import CKEditorUtilities from '../mixins/CKEditorUtilities'
+
+export default {
+    mixins: [CKEditor, DoesAxiosRequests, CKEditorUtilities, EmitsEvents, HasId, HasConfig],
+    data(){
+        return {
+
+        }
+    },
+    methods: {
+        onOpen(value, event){ //not used anymore
+            return
+        },
+        onChange(value, event){ //not used anymore
+            return
+        },
+        onClose(value, event){
+            value = value.substr(0, 16)
+            var html = '<span class="mention ckeditor-mention icon-calendar" data-mention="icon-calendar|'+value+'">'+value+'</span>'
+            this.insertHtml(html)
+        },
+    },
+    created(){
+        return
+    }
+
+}
+</script>
+

package/kompo-ckeditor-1.0.17/komponents/EditableCKEditor.vue

@@ -0,0 +1,42 @@
+<template>
+    <div class="vlEditableWrapper">
+        <div 
+            class="vlEditableContent cursor-pointer" 
+            v-if="!editing" 
+            v-html="$_value || $_label" 
+            @click.stop="startEditing"/>
+        
+        <VlCKEditor
+            v-if="editing" 
+            :vkompo="component"
+            v-click-out="close"
+            @change="change"/>
+    </div>
+</template>
+
+<script>
+import CKEditor from '../mixins/CKEditor'
+export default {
+    mixins: [CKEditor],
+    data(){
+        return {
+            editing: false
+        }
+    },
+    computed: {
+
+    },
+    methods: {
+        startEditing(){
+            this.editing = true
+        },
+        close(){
+            this.editing = !this.editing
+        },
+        change(value){
+            this.component.value = value
+        }
+    }
+}
+</script>
+

package/kompo-ckeditor-1.0.17/komponents/TranslatableEditor.vue

@@ -0,0 +1,28 @@
+<template>
+    <vl-form-field v-bind="$_wrapperAttributes">
+        <vlLocaleTabs 
+            :locales="locales" 
+            :activeLocale="activeLocale"
+            @changeLocale="changeTab"/>
+        <ckeditor 
+            class="vlFormControl"
+            ref="content"
+            v-model="currentTranslation" 
+            v-bind="$_attributes"
+            v-on="$_events"
+            @keydown.stop
+            
+            :editor="editor" 
+            :config="editorConfig" />
+    </vl-form-field>
+</template>
+
+<script>
+import CKEditor from '../mixins/CKEditor'
+import Translatable from 'vue-kompo/js/form/mixins/Translatable'
+
+export default {
+    mixins: [CKEditor, Translatable],
+}
+</script>
+