@peter.naydenov/cuts 1.5.0 → 2.0.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@peter.naydenov/cuts",
   "description": "SPA scene manager",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "license": "MIT",
   "author": "Peter Naydenov",
   "main": "./src/main.js",
@@ -31,24 +31,24 @@
     "url": "git+https://github.com/PeterNaydenov/cuts.git"
   },
   "devDependencies": {
-    "@peter.naydenov/visual-controller-for-vue3": "^2.1.6",
-    "@rollup/plugin-commonjs": "^28.0.8",
+    "@peter.naydenov/visual-controller-for-vue3": "^2.1.7",
+    "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@types/node": "^24.9.1",
+    "@types/node": "^24.10.0",
     "@vitejs/plugin-vue": "^6.0.1",
-    "@vitest/coverage-v8": "^4.0.1",
-    "cypress": "^15.5.0",
-    "rollup": "^4.52.5",
+    "@vitest/coverage-v8": "^4.0.8",
+    "cypress": "^15.6.0",
+    "rollup": "^4.53.1",
     "typescript": "^5.9.3",
-    "vite": "^7.1.11",
-    "vitest": "^4.0.1",
-    "vue": "^3.5.22"
+    "vite": "^7.2.2",
+    "vitest": "^4.0.8",
+    "vue": "^3.5.24"
   },
   "dependencies": {
     "@peter.naydenov/log": "^1.1.1",
-    "@peter.naydenov/shortcuts": "^3.5.1",
-    "ask-for-promise": "^3.0.2"
+    "@peter.naydenov/shortcuts": "^4.0.0",
+    "ask-for-promise": "^3.1.0"
   },
   "keywords": [
     "script",

package/src/findInstructions.js

@@ -20,13 +20,7 @@ function* findInstructions ( currentName, currentParents, targetName, targetPare
         } 
 
     if ( targetParents.length === 0 ) {  // Need to close all current parents, then open the target
-            if ( !currentParents ) {
-                    yield [ currentName, 'hide' ]
-                    yield [ targetName, 'show'   ]
-                    return
-                }
             yield [ currentName, 'hide' ]
-
             if ( currentParents.includes ( targetName ) ) {
                     let index = currentParents.indexOf ( targetName );
                     let filtered = currentParents.filter ( (x,i) => i > index )

package/src/main.js

@@ -8,12 +8,14 @@
  *  History notes:
  *    - Started as @peter.naydenov/screen-writer on gitHub for the first time on 2023-11-24;
  *    - Version 2.0.0 of screen-writer. Works with shortcuts@3.0.1. Published on March 6th, 2024;
+ *    - Version 2.0.0 of cuts. Works with shortcuts@4.0.0. Published on November 9th, 2025;
  *    - Rename to @peter.naydenov/cuts 
  *      Changes in documentation and some methods were renamed accordingly. 
  *      Version 1.0.0. 
  *      Published for first time as package '@peter.naydenov/cuts' on May 8th, 2024;
  *      Extend 'scene' with optional 'afterShow' and 'beforeHide' methods. December 21st, 2024;
  *    - Shortcuts@3.2.x. Plugin 'form' is available. August 15th, 2025;
+ *    - Shortcuts@4.0.0. New plugins 'scroll' and 'hover' are available. November 9th, 2025;
  */
 
 
@@ -37,8 +39,13 @@ import jumpsReset    from './methods/jumpsReset.js'
 function main ( cfg= {logLevel:0} ) {
      const 
           shortcutMngr = shortcuts ({ errorEventName: '@app-error' })
-        , logLevel = cfg.logLevel || 0
-        , log = createLog ({ level:logLevel })
+        , logLevel = cfg.logLevel || 1
+        , log = createLog ({ level:logLevel }, (arg) => {
+                                            const { type } = arg;
+                                            if ( type === 'error' ) {  
+                                                      shortcutMngr.emit ( '@app-error', arg )
+                                                  }
+                                      })
         , state = {     
                      currentScene   : null       // Current scene name;
                    , currentParents : null       // Current scene parents if any;
@@ -69,10 +76,10 @@ function main ( cfg= {logLevel:0} ) {
         API.jumpsReset    = jumpsReset ( state )
 
         /**
-         * @typedef {'Key'|'Click'|'Form' } pluginNames
-         * @description List of possible plugin names: 'Key', 'Click', 'Form'
+         * @typedef {'Key'|'Click'|'Form'|'Hover'|'Scroll' } pluginNames
+         * @description List of possible plugin names: 'Key', 'Click', 'Form', 'Hover', 'Scroll'
          * 
-         * Load a needed shortcut plugins - 'Key', 'Click', 'Form' and so on.
+         * Load a needed shortcut plugins - 'Key', 'Click', 'Form', 'Hover', 'Scroll' and so on.
          * It's a async function. Don't forget to 'await' it.
          * @function loadPlugins
          * @param {Array.<pluginNames>} plugins - list of plugins to load
@@ -109,7 +116,7 @@ function main ( cfg= {logLevel:0} ) {
          * @param {string} note - note, provided to action functions
          * @returns void
          */
-        API.setNote         = note => shortcuts.setNote ( note )
+         API.setNote         = note => shortcutMngr.setNote ( note )
 
         /**
          * @function listScenes

package/src/methods/setScenes.js

@@ -1,11 +1,15 @@
 'use strict'
 
 
+/**
+ * @typedef {Object} AskObject
+ * @property {function} done - Mark the task as done
+ */
 /**
  * @typedef {Object} SceneObject
- * @property {function} show - load interface and prerequisites for the scene;
+ * @property {function({task: AskObject, dependencies: *}): void} show - load interface and prerequisites for the scene;
  * @property {function():boolean} [afterShow] - run after scene is loaded. Optional. Returns true to continue loading, false to cancel;
- * @property {function():void} hide - Reverse the settings from 'show';
+ * @property {function({task: AskObject, dependencies: *}): void} hide - Reverse the settings from 'show';
  * @property {function():void} [beforeHide] - Run before scene is hidden. Optional;
  * @property {Array.<string>} [parents] - list of parent scene names.
  * @property {*} ... - shortcut descriptions
@@ -30,15 +34,27 @@ function setScenes ( dependencies, state ) {
       * @description Screen Description is an object with fields 'name' and 'scene'
       */
     return function setScenes ( list ) {
-    const { shortcutMngr } = dependencies;
-    list.forEach ( item => {
-                    if ( item == null ) return
-                    const {name, scene } = item;
-                    if ( scene == null ) {
-                            console.warn ( `Scene ${name} is not defined` )
-                            return
-                      }
-                    if ( !scene.parents ) scene.parents = []
+    const { shortcutMngr, log } = dependencies;
+     list.forEach ( item => {
+                     if ( item == null ) return
+                     const {name, scene } = item;
+                     if ( !name ) {
+                              log ({
+                                           message: `Scene name is not defined`
+                                         , level : 1
+                                         , type  : 'error'
+                                     })
+                             return
+                       }
+                     if ( scene == null ) {
+                              log ({
+                                           message: `Scene ${name} is not defined`
+                                         , level : 1
+                                         , type  : 'error'
+                                     })
+                             return
+                       }
+                    if ( ! scene.parents )   scene.parents = []
                     state.scenes[name] = scene
                     state.sceneNames.add ( name )
                     

package/src/methods/show.js

@@ -24,8 +24,10 @@ function show ( dependencies, state ) {
 
     if ( hasBeforeHide ) { // Execute 'beforeUnload' function if exists
                 const closingFn = scenes[currentScene].beforeHide;
+                // TODO: If async elements in beforeUnload, we will 
+                // need full unloadTask and function should return a promise
                 closingFn ({ done:unloadTask.done, dependencies: shortcutMngr.getDependencies() })
-        } // if currentPage
+        } // if currentScene
     else  unloadTask.done ( true )
 
 
@@ -38,21 +40,19 @@ function show ( dependencies, state ) {
                         }
                         
                     if ( !sceneNames.has ( requestedScene ) ) {
-                            if ( log ) {
-                                            log ({
-                                                      message: `Scene ${requestedScene} is not available.`
-                                                    , level : 1
-                                                    , type  : 'error'
-                                                })
-                                            showTask.done ()
-                                            return showTask.promise
-                                }
+                                log ({
+                                          message: `Scene "${requestedScene}" is not available.`
+                                        , level : 1
+                                        , type  : 'error'
+                                    })
+                                showTask.done ()
+                                return showTask.promise
                         }
                         
                     if ( !opened && options.ssr ) {  // Check for Server side rendering on first scene load only
                                 // Executes only once when the scene manager is started
                                 state.opened = true
-                                state.currentPage = requestedScene
+                                state.currentScene = requestedScene
                                 shortcutMngr.changeContext ( requestedScene )
                                 showTask.done ()
                                 return showTask.promise
@@ -60,23 +60,22 @@ function show ( dependencies, state ) {
                     
                     const { show, parents=[] } = scenes[requestedScene];
                     
-                    if ( parents[0] === '*' ) {
-                                show ().then ( () => showTask.done ()   )
-                                state.currentParents.push ( state.currentPage )
-                                state.currentPage = requestedScene
-                                return showTask.promise
-                        }
-                    
-                    let checkParents = parents.forEach ( name => sceneNames.has ( name )   ) || true ;
+                     if ( parents[0] === '*' ) {
+                                 const overlayTask = setInstruction(show, ...args)()
+                                 overlayTask.then ( () => showTask.done ()   )
+                                 state.currentParents.push ( state.currentScene )
+                                 state.currentScene = requestedScene
+                                 return showTask.promise
+                         }
+
+                    let checkParents = ( parents.length === 0 ) ? true : parents.every ( name => sceneNames.has ( name )   )
                     
                     if ( !checkParents ) {
-                                if ( log ) {
-                                                log ({
-                                                          message: `Some of '${requestedScene}' parent scenes are not set.`
-                                                        , level : 1
-                                                        , type  : 'error'
-                                                    })
-                                    }
+                                log ({
+                                          message: `Some of '${requestedScene}' parent scenes are not set.`
+                                        , level : 1
+                                        , type  : 'error'
+                                    })
                                 showTask.done ()
                                 return showTask.promise
                         }
@@ -109,7 +108,7 @@ function show ( dependencies, state ) {
                     
                     goingTask.onComplete ( () => {
                                         state.opened = true
-                                        state.currentPage = requestedScene
+                                        state.currentScene = requestedScene
                                         state.currentParents = scenes[requestedScene].parents || null 
                                         shortcutMngr.changeContext ( requestedScene )                                        
                                         if ( typeof scenes[requestedScene].afterShow === 'function' )   scenes[requestedScene].afterShow ({ dependencies: shortcutMngr.getDependencies(), done: () => {} })

package/test/01-general.cy.js

@@ -0,0 +1,348 @@
+'use strict'
+
+import VisualController from '@peter.naydenov/visual-controller-for-vue3' // Docs : https://github.com/PeterNaydenov/visual-controller-for-vue3
+import { expect } from 'chai'
+import cuts from '../src/main.js'
+import { pluginClick } from '@peter.naydenov/shortcuts'
+
+import Dummy from './dummy.vue'
+import Red from './red.vue'
+import Blue from './blue.vue'
+import Gray from './gray.vue'
+
+
+
+describe ( 'General', () => {
+    
+    it ( 'Start a sreenWriter. ScreenWriter API', () => {
+                const script = cuts ();
+                expect ( script ).to.have.property ( 'show' )
+                expect ( script ).to.have.property ( 'hide' )
+                expect ( script ).to.have.property ( 'setScenes' )
+                expect ( script ).to.have.property ( 'setNote' )
+                expect ( script ).to.have.property ( 'listScenes' )
+                expect ( script ).to.have.property ( 'listShortcuts' )
+                expect ( script ).to.have.property ( 'setDependencies' )
+                expect ( script ).to.have.property ( 'getDependencies' )
+        }) // it start a director
+
+
+
+    it ( 'Load a top level page', done => {
+                let 
+                      render = false
+                    , click = false
+                    , html = new VisualController ()
+                    ;
+                const 
+                      script = cuts ()
+                    , d = document.querySelector ('[data-cy-root]')
+                    , testScene = { 
+                                      show : ({ task, dependencies }) => {
+                                                const { html } = dependencies;
+                                                html.publish ( Red, {}, 'container' )
+                                                render = true
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) => {
+                                                const { html } = dependencies;
+                                                html.destroy ( 'container' )
+                                                task.done ()
+                                            }
+                                    , 'click: left-1' : ({dependencies,target}) => {
+                                                    click = true
+                                                }
+                            }
+                    ;
+                script.enablePlugin ( pluginClick )
+                d.id = 'root'
+                html.publish ( Dummy, {}, 'root' ) 
+
+                cy.wait ( 0 )
+                    .then ( () => {
+                            script.setDependencies ({ html })
+                            script.setScenes ([ 
+                                                  { name:'test', scene:testScene } 
+                                            ])
+                            script.show ({ scene : 'test' })
+                            // cy.get ( '#target' ).click ()
+                        })
+                    .then ( () => {
+                            expect ( render ).to.be.true
+                            // expect ( click ).to.be.true
+                            return cy.wait ( 0 )
+                        })
+                    .then ( () => {
+                            return script.hide ()
+                        })
+                    .then ( () => {
+                            const pageContent = document.getElementById('container').innerHTML
+                            expect ( pageContent ).to.be.empty
+                            done ()
+                        })
+        }) // it load a top level page
+
+
+
+    it ( 'Load a deep level page', done => {
+            let 
+                  render = false
+                , click = false
+                , html = new VisualController ()
+                ;
+            const 
+                  script = cuts ()
+                , d = document.querySelector ('[data-cy-root]' )
+                , testScene = { 
+                                  show : ({ task, dependencies }) => {
+                                            const { html } = dependencies;
+                                            html.publish ( Red, {}, 'container' )
+                                            render = true
+                                            task.done ()
+                                        }
+                                , hide : ({task, dependencies}) => {
+                                            const { html } = dependencies;
+                                            html.destroy ( 'container' )
+                                            task.done ()
+                                        }
+                                , parents : [ 'blue' ]
+                                , 'click: 1-left' : ({dependencies,target}) => { // Order in the event name after the prefix is not important
+                                                click = true
+                                            }
+                        }
+                , bluePage = {
+                                      show : ({ task, dependencies }) => {
+                                                const { html } = dependencies;
+                                                html.publish ( Blue, {}, 'blue' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) => {
+                                                const { html } = dependencies;
+                                                html.destroy ( 'blue' )
+                                                task.done ()
+                                            }
+                                    , 'click: left-1' : ({dependencies,target}) => {}
+                        }
+                ;
+            script.enablePlugin ( pluginClick )
+            d.id = 'root'
+            html.publish ( Dummy, {}, 'root' )
+
+            cy.wait ( 0 )
+                .then ( () => {
+                        script.setDependencies ({ html })
+                        script.setScenes ([ 
+                                              { name:'test' , scene : testScene } 
+                                            , { name: 'blue', scene : bluePage  }
+                                        ])
+                        script.show ({ scene: 'test' })
+                        cy.get ( '#target' ).click ()
+                    })
+                .then ( () => {
+                        expect ( render ).to.be.true
+                        expect ( click ).to.be.true
+                        return cy.wait ( 0 )
+                    })
+                .then ( () => {
+                        return script.hide ( '*' )
+                    })
+                .then ( () => {
+                        const pageContent = document.getElementById('container').innerHTML
+                        expect ( pageContent ).to.be.empty
+                        done ()
+                    })
+        }) // it load a deep level page
+
+
+
+    it ( 'Turn to other branch', done => {
+            let 
+                  render = false
+                , click = false
+                , html = new VisualController ()
+                ;
+            const 
+                  script = cuts ()
+                , d = document.querySelector ('[data-cy-root]' )
+                , testScene = { 
+                                  show : ({ task, dependencies }) => {
+                                            const { html } = dependencies;
+                                            html.publish ( Red, {}, 'subgray' )   // subgray is inside 'blue' component
+                                            render = true
+                                            task.done ()
+                                        }
+                                , hide : ({task, dependencies}) => {
+                                            const { html } = dependencies;
+                                            html.destroy ( 'subgray' )
+                                            task.done ()
+                                        }
+                                , parents : [ 'blue' ]
+                                , 'click: left-1' : ({dependencies,target}) => {
+                                                click = true
+                                            }
+                        }
+                , bluePage = {
+                                      show : ({ task, dependencies }) => {
+                                                const { html } = dependencies;
+                                                html.publish ( Blue, {}, 'blue' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) => {
+                                                const { html } = dependencies;
+                                                html.destroy ( 'blue' )
+                                                task.done ()
+                                            }
+                                    , 'click: left-1' : ({dependencies,target}) => {}
+                        }
+                , grayPage = {
+                                      show : ({ task, dependencies }) => {
+                                                const { html } = dependencies;
+                                                html.publish ( Gray, {}, 'subgray' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) => {
+                                                const { html } = dependencies;
+                                                html.destroy ( 'subgray' )
+                                                task.done ()
+                                            }
+                                    , parents : [ 'blue' ]
+                                    , 'click: left-1' : ({dependencies,target}) => {}
+                        }
+                ;
+            script.enablePlugin ( pluginClick )
+            d.id = 'root'
+            html.publish ( Dummy, {}, 'root' )
+
+            cy.wait ( 0 )
+                .then ( () => {
+                        script.setDependencies ({ html })
+                        script.setScenes ([ 
+                                              { name:'test', scene  : testScene } 
+                                            , { name: 'blue', scene : bluePage  }
+                                            , { name: 'gray', scene : grayPage  }
+                                        ])
+                        script.show ({ scene : 'test' })
+                        cy.get ( '#target' ).click ()
+                    })
+                .then ( () => {
+                        expect ( render ).to.be.true
+                        expect ( click ).to.be.true
+                        return cy.wait ( 0 )
+                    })
+                .then ( () => script.show ({ scene : 'gray' }  ))
+                .then ( () => {
+                        const 
+                              red = document.querySelectorAll ( '.red' )
+                            , blue = document.querySelectorAll ( '.gray' )
+                            ;
+                        expect ( blue.length ).to.be.equal ( 1 )
+                        expect ( red.length ).to.be.equal  ( 0 )
+                        done ()
+                    })
+    }) // it turn to other branch
+
+
+
+    it ( 'Jump and jumpBack', done => {
+            const 
+                  script = cuts ()
+                , myLocations = []
+                , testScene = { 
+                                  show : ({ task, dependencies }) => {
+                                            myLocations.push ( 'test scene' )
+                                            task.done ()
+                                        }
+                                , hide : ({task, dependencies}) =>  task.done ()
+                        }
+                , bluePage = {
+                                      show : ({ task, dependencies }) => {
+                                                myLocations.push ( 'blue scene' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) =>  task.done ()
+                                    , 'click: left-1' : ({dependencies,target}) => {}
+                        }
+                , grayPage = {
+                                      show : ({ task, dependencies }) => {
+                                                myLocations.push ( 'gray scene' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) =>  task.done ()
+                        }
+                ;
+
+            script.setScenes ([ 
+                                  { name:'test',  scene : testScene } 
+                                , { name: 'blue', scene : bluePage  }
+                                , { name: 'gray', scene : grayPage  }
+                            ])
+
+            script.show ({ scene : 'test' })
+                  .then ( () =>  script.jump ({ scene : 'blue' })) // Go from test to blue. Remember 'test'
+                  .then ( () =>  script.jump ({ scene : 'gray' })) // Go from blue to gray. Remember 'blue'
+                  .then ( () =>  script.jumpBack ()) // Go back to blue. Taken from the stack
+                  .then ( () =>  script.jumpBack ()) // Go back to test. Taken from the stack
+                  .then ( () =>  script.jumpBack ()) // this should do nothing - no more back hops in stack
+                  .then ( () =>  {
+                        expect ( myLocations ).to.be.deep.equal ([ 
+                                                'test scene', 
+                                                'blue scene', 
+                                                'gray scene', 
+                                                'blue scene', 
+                                                'test scene' 
+                                            ])
+                        done ()   
+                    })
+        }) // it jump
+
+
+
+    it ( 'Jump and jumpsReset', done => {
+            const 
+                  script = cuts ()
+                , myLocations = []
+                , testScene = { 
+                                  show : ({ task, dependencies }) => {
+                                            myLocations.push ( 'test scene' )
+                                            task.done ()
+                                        }
+                                , hide : ({task, dependencies}) =>  task.done ()
+                        }
+                , bluePage = {
+                                      show : ({ task, dependencies }) => {
+                                                myLocations.push ( 'blue scene' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) =>  task.done ()
+                                    , 'click: left-1' : ({dependencies,target}) => {}
+                        }
+                , grayPage = {
+                                      show : ({ task, dependencies }) => {
+                                                myLocations.push ( 'gray scene' )
+                                                task.done ()
+                                            }
+                                    , hide : ({task, dependencies}) =>  task.done ()
+                        }
+                ;
+
+            script.setScenes ([ 
+                                  { name:'test',  scene : testScene } 
+                                , { name: 'blue', scene : bluePage  }
+                                , { name: 'gray', scene : grayPage  }
+                            ])
+
+            script.show ({ scene : 'test' })
+                  .then ( () =>  script.jump ({ scene : 'blue' })) // Go from test to blue. Remember 'test'
+                  .then ( () =>  script.jump ({ scene : 'gray' })) // Go from blue to gray. Remember 'blue'
+                  .then ( () =>  script.jumpsReset () ) // Clear the jump stack
+                  .then ( () =>  script.jumpBack ()) // This should do nothing - no back hops
+                  .then ( () =>  {
+                        expect ( myLocations ).to.be.deep.equal ([ 
+                                                'test scene', 
+                                                'blue scene', 
+                                                'gray scene', 
+                                            ])
+                        done ()   
+                    })
+        }) // it jump
+}) // describe

package/test/blue.vue

@@ -0,0 +1,13 @@
+<template>
+    <div class="blue">
+        <div id="subgray"></div>
+    </div>
+</template>
+
+<style scoped>
+    .blue {
+        width: 200px;
+        height: 200px;
+        background-color: skyblue;
+    }
+</style>

package/test/dummy.vue

@@ -0,0 +1,34 @@
+<template>
+    <div>
+        <h1>Test</h1>
+        <p id="target">Test <a href="#">lorem ipsum</a></p>
+        <div id="container">
+            
+        </div>
+        <div id="blue"></div>
+        <div id="gray"></div>
+    </div>
+</template>
+
+<style>
+:root {
+    --blue: #007bff;
+    --gray: #6c757d;
+    --link-color: rgb(204, 51, 10);
+}
+
+body.dark {
+    --background-color: #000;
+    --link-color: rgb(249, 249, 249);
+    background-color: var(--background-color);
+}
+
+#target {
+    --blue: var(--link-color);
+     color: var(--blue);
+}
+
+#target a {
+    color: var(--link-color);
+}
+</style>