Merge pull request #85 from KaliedaRik/v8-dev

Release to v8.13.0
KaliedaRik · Apr 28, 2024 · da00f72 · da00f72
2 parents a2c9e99 + 799c252
commit da00f72
Show file tree

Hide file tree

Showing 1,000 changed files with 97,394 additions and 91,269 deletions.
diff --git a/LICENSE.md b/LICENSE.md
@@ -1,9 +1,5 @@
-The MIT License (MIT)
-
-Permission is hereby granted, free of charge, to any person ("You") obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS, CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-If You choose to offer this Software, in whole or part, as a component or product in a jurisdiction requiring lifecycle duty of care You agree to indemnify, defend, and hold each contributor to the Software (the "Contributors") harmless for any liability incurred by, or claims asserted against, such Contributors by reason of Your actions in such a jurisdiction.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,5 +1,5 @@
 # Welcome to the Scrawl-canvas Library
-Version: `8.12.0 - 12 January 2024` 
+Version: `8.13.0 - 27 April 2024` 
 
 Scrawl-canvas website: [scrawl-v8.rikweb.org.uk](https://scrawl-v8.rikweb.org.uk).
 + learning materials: [scrawl-v8.rikweb.org.uk/learn](https://scrawl-v8.rikweb.org.uk/learn).
@@ -58,7 +58,7 @@ There are three main ways to include Scrawl-canvas in your project:
 2. Unzip the file to a folder in your project. 
 3. Import the library into the script code where you will be using it.
 
-Alternatively, a zip package of the v8.12.0 files can be downloaded from this link: [scrawl.rikweb.org.uk/downloads/scrawl-canvas_8-12-0.zip](https://scrawl.rikweb.org.uk/downloads/scrawl-canvas_8-12-0.zip) - that package only includes the minified file.
+Alternatively, a zip package of the v8.13.0 files can be downloaded from this link: [scrawl.rikweb.org.uk/downloads/scrawl-canvas_8-13-0.zip](https://scrawl.rikweb.org.uk/downloads/scrawl-canvas_8-13-0.zip) - that package only includes the minified file.
 
 ```html
 <!-- Hello world -->
@@ -69,28 +69,24 @@ Alternatively, a zip package of the v8.12.0 files can be downloaded from this li
 </head>
 <body>
 
-    <canvas id="mycanvas"></canvas>
+    <canvas id="my-canvas"></canvas>
 
     <!-- The library is entirely modular and needs to be imported into a module script -->
     <script type="module">
 
         import * as scrawl from './relative-or-absolute/path/to/scrawl-canvas/min/scrawl.js';
 
         // Get a handle to the canvas element
-        let canvas = scrawl.library.canvas.mycanvas;
+        let canvas = scrawl.findCanvas('my-canvas');
 
         // Setup the scene to be displayed in the canvas
-        scrawl.makePhrase({
+        scrawl.makeLabel({
 
             name: 'hello',
-            text: 'Hello, World!',
-
-            width: '100%',
+            start: [20, 20],
 
-            startX: 20,
-            startY: 20,
-
-            font: 'bold 40px Garamond, serif',
+            text: 'Hello, World!',
+            fontString: 'bold 40px Garamond, serif',
         });
 
         // Render the canvas scene once
@@ -106,7 +102,7 @@ Alternatively, a zip package of the v8.12.0 files can be downloaded from this li
 This will pull the requested npm package directly into your web page:
 ```html
 <script type="module">
-    import * as scrawl from 'https://unpkg.com/scrawl-canvas@8.12.0';
+    import * as scrawl from 'https://unpkg.com/scrawl-canvas@8.13.0';
     [...]
 </script>
 ```
@@ -133,17 +129,17 @@ import * as scrawl from 'scrawl-canvas';
 After forking this repo down to your local machine, `cd` into the scrawl-canvas folder, run `yarn install` or `npm install` (for the local build toolchain - the library itself has no external dependencies) and start a local server.
 
 ```sh
-$> cd ./path/to/Scrawl-canvas
+$> cd ./path/to/Scrawl-canvas/folder
 $> yarn install
 $> yarn dev
 ```
 
 ### Testing
 The code base does not include any ___unit testing___ frameworks. Instead, we rely on a set of Demo tests which allow us to perform ___integration testing___ and ___user interface testing___.
 
-Why this approach? Because most of the Scrawl-canvas functionality revolves around various forms of animation, which requires visual inspection of the Demo tests to check that the canvas display - and thus, by inference, the underlying code - performs as expected.
+Why this approach? Because most of the Scrawl-canvas functionality revolves around various forms of user interaction and animation, which requires visual inspection of the Demo tests to check that the canvas display - and thus, by inference, the underlying code - performs as expected.
 
-Most Demos include some form of user interaction, which allows us to test specific aspects of the code base.
+Demos that include user interaction allow us to test specific aspects of the code base.
 
 #### Linting
 The tool chain includes the [ESLint](https://eslint.org/) package to impose some basic checks on code. We use the default checks supplied by the package (as indicated in the [rules documentation page](https://eslint.org/docs/latest/rules)). To run the linter:

diff --git a/demo/canvas-001.html b/demo/canvas-001.html
@@ -6,23 +6,59 @@
   <meta http-equiv="x-ua-compatible" content="ie=edge">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Demo Canvas 001</title>
+  <link rel='icon' type='image/png' href='/favicon.png'>
   <link href="css/normalize.css" rel="stylesheet" />
   <link href="css/tests.css" rel="stylesheet" />
+  <style>
+    /* For progressive enhancement */
+    .canvas-progressive-enhancement-wrapper {
+      display: flex;
+      justify-content: center;
+
+      & canvas {
+        box-shadow: 0px 0px 0px 1px black;
+
+        /* In no-JS environments, the image should display in place of the canvas element */
+        & .placeholder {
+          text-align: center;
+          width: 600px;
+          max-width: 100%;
+
+          & img {
+            width: 100%;
+          }
+        }
+      }
+    }
+  </style>
 </head>
 
 <body>
+  <div id="test-navigation">
+    <a href="index.html">&larr; Previous</a>
+    <a href="canvas-002.html">Next &rarr;</a>
+  </div>
   <h1><a href="index.html">Scrawl-canvas v8</a> - Canvas test 001</h1>
   <h2>Block and wheel entitys (make, clone, method)<br />Drag and drop block and wheel entitys</h2>
 
-  <canvas 
-    id="mycanvas" 
-    width="600" 
-    height="600"
-    data-scrawl-canvas
-    data-base-background-color="aliceblue"
-  ></canvas>
+  <div class="canvas-progressive-enhancement-wrapper">
+    <canvas 
+      id="mycanvas" 
+      width="600" 
+      height="600"
+      data-scrawl-canvas
+      data-base-background-color="aliceblue"
+    >
+      <div class="placeholder">
+        <img
+          src="thumbs/canvas-001.webp"
+          alt="Screen capture image of the demo canvas"
+        />    
+      </div>
+    </canvas>
+  </div>
 
-  <p id="reportmessage"></p>
+  <p id="reportmessage" role="timer" aria-live="polite">To note: Javascript is not running in this browser environment. The canvas element is ignored; instead a placeholder image displays where the canvas would have appeared.</p>
 
   <div class="testinfo">
     <h4>Test purpose</h4>

diff --git a/demo/canvas-001.js b/demo/canvas-001.js
@@ -2,54 +2,22 @@
 // Block and Wheel entitys (make, clone, method); drag and drop block and wheel entitys
 
 // [Run code](../../demo/canvas-001.html)
-
-// Various ways to import the SAcrawl-canvas library, depending on project requirements
-// ```
-// // If library has been added to a project build using npm/yarn/etc and is being bundled:
-// import scrawl from 'scrawl';
-//
-// // If library has been added to a public/dist folder in the code base:
-// import scrawl from './path/to/min/scrawl.js';
-//
-// // If library is imported from a Content Distribution Network endpoint:
-// import scrawl from 'https://path/to/cdn/endpoint/scrawl-canvas';
-//
-// // If the library is to be used in a TypeScript project, or for tree-shaking[1], then functions need to be imported individually:
-// import {
-//     makeBlock,
-//     makeWheel,
-// } from 'relevant-library-path-source';
-//
-// // ...Or, alternatively, using the * notation:
-// import * as scrawl from 'relevant-library-path-source';
-//
-// // [1] - Tree-shaking functionality to help package managers reduce the size of the shipped library code is on the road map for delivery as part of SC version 9.0.0
-// ```
-//
-// + All testing Demos use the TS version for loading the library, so we can test the library's .d.ts TypeScript definitions file against them (SC doesn't use TS internally). Other approaches tend to generate a TypeScript error claiming (wrongly) that the library doesn't have a default export.
-import {
-    library as L,
-    makeBlock,
-    makeDragZone,
-    makeRender,
-    makeWheel,
-} from '../source/scrawl.js';
+import * as scrawl from '../source/scrawl.js';
 
 import { reportSpeed, killArtefact } from './utilities.js';
 
 
 // #### Scene setup
 // Get a handle to the Canvas wrapper
-const canvas = L.artefact.mycanvas;
-
+const canvas = scrawl.findCanvas('mycanvas');
 
 // Namespacing boilerplate
-const namespace = 'demo';
+const namespace = canvas.name;
 const name = (n) => `${namespace}-${n}`;
 
 
 // Create and clone block entitys
-makeBlock({
+scrawl.makeBlock({
     name: name('block-fill'),
     width: 100,
     height: 100,
@@ -102,7 +70,7 @@ makeBlock({
 
 
 // Create and clone Wheel entitys
-makeWheel({
+scrawl.makeWheel({
     name: name('wheel-fill'),
     radius: 50,
     startAngle: 15,
@@ -160,48 +128,85 @@ makeWheel({
 
 
 // Change the fill and stroke styles on one of the blocks, and one of the wheels, and any entitys sharing their respective states
-L.artefact[name('block-fillAndDraw')].set({
+// + This is also a test to make sure the library `findXYZ` functions are working
+scrawl.findArtefact(name('block-fillAndDraw')).set({
     fillStyle: 'blue',
     strokeStyle: 'coral'
 });
 
-// Entitys can be found in both the 'artefact' and 'entity' sections of the library
-L.entity[name('wheel-fillAndDraw')].set({
+scrawl.findEntity(name('wheel-fillAndDraw')).set({
     fillStyle: 'blue',
     strokeStyle: 'coral'
 });
 
 
 // #### User interaction
+// Make an object to hold functions we'll use for UI
+const setCursorTo = {
+
+    auto: () => {
+        canvas.set({
+            css: {
+                cursor: 'auto',
+            },
+        });
+    },
+    pointer: () => {
+        canvas.set({
+            css: {
+                cursor: 'grab',
+            },
+        });
+    },
+    grabbing: () => {
+        canvas.set({
+            css: {
+                cursor: 'grabbing',
+            },
+        });
+    },
+};
+
 // Create the drag-and-drop zone
-const current = makeDragZone({
+const current = scrawl.makeDragZone({
 
     zone: canvas,
     endOn: ['up', 'leave'],
     exposeCurrentArtefact: true,
     preventTouchDefaultWhenDragging: true,
+    updateOnStart: setCursorTo.grabbing,
+    updateOnEnd: setCursorTo.pointer,
+});
+
+// Implement the hover check on the Canvas wrapper
+canvas.set({
+    checkForEntityHover: true,
+    onEntityHover: setCursorTo.pointer,
+    onEntityNoHover: setCursorTo.auto,
 });
 
 
 // #### Scene animation
 // Function to display frames-per-second data, and other information relevant to the demo
 const report = reportSpeed('#reportmessage', function () {
+
     const dragging = current();
     return `Currently dragging: ${(typeof dragging !== 'boolean' && dragging) ? dragging.artefact.name : 'nothing'}`;
 });
 
 
 // Create the Display cycle animation
-makeRender({
+scrawl.makeRender({
 
     name: name('animation'),
     target: canvas,
+    commence: () => canvas.checkHover(),
     afterShow: report,
 });
 
 
 // #### Development and testing
-console.log(L);
+console.log(scrawl.library);
 
 console.log('Performing tests ...');