143 - experiment - improved jsdoc and exported to a type definition file

.gitignore

@@ -4,6 +4,7 @@
 *.iml
 node_modules
 /dist/
+/types/
 cypress/videos
 cypress/screenshots
 

package.json

@@ -3,20 +3,23 @@
   "svelte": "src/index.js",
   "module": "dist/index.mjs",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "scripts": {
     "test": "cypress run",
-    "build": "rollup -c",
+    "build": "tsc && rollup -c && sed -i '' \"s/^namespace/declare namespace/g\" dist/index.d.ts",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {},
   "devDependencies": {
     "@babel/core": "^7.9.6",
     "@babel/preset-env": "^7.9.6",
+    "@rollup/plugin-node-resolve": "^6.0.0",
     "babel-jest": "^26.0.1",
     "cypress": "^4.5.0",
-    "@rollup/plugin-node-resolve": "^6.0.0",
+    "rollup": "^1.20.0",
     "rollup-plugin-babel": "^4.3.2",
-    "rollup": "^1.20.0"
+    "rollup-plugin-dts": "^1.4.13",
+    "typescript": "^4.0.3"
   },
   "keywords": [
     "svelte",

rollup.config.js

@@ -1,4 +1,5 @@
 import resolve from '@rollup/plugin-node-resolve';
+import dts from "rollup-plugin-dts";
 import babel from 'rollup-plugin-babel'
 import pkg from './package.json';
 
@@ -7,7 +8,7 @@ const name = pkg.name
     .replace(/^\w/, m => m.toUpperCase())
     .replace(/-\w/g, m => m[1].toUpperCase());
 
-export default {
+export default [{
     input: 'src/index.js',
     output: [
         { file: pkg.module, 'format': 'es' },
@@ -23,4 +24,8 @@ export default {
         }),
         resolve()
     ]
-};
+}, {
+    input: "./types/index.d.ts",
+    output: [{ file: "dist/index.d.ts", format: "es" }],
+    plugins: [dts()],
+}];

src/action.js

@@ -4,33 +4,64 @@ import {ITEM_ID_KEY} from "./constants";
 import {toString} from "./helpers/util";
 
 /**
- * A custom action to turn any container to a dnd zone and all of its direct children to draggables
- * Supports mouse, touch and keyboard interactions.
- * Dispatches two events that the container is expected to react to by modifying its list of items,
- * which will then feed back in to this action via the update function
- *
+ * @callback TransformDraggedElementFunc
+ * @param {HTMLElement} draggedElement
+ * @param {object} [draggedElementData] - the relevant entry from the provided items array
+ * @param {number} [index] - the would be index of the dragged element if it is dropped
+ * @return {void}
+ */
+
+/**
  * @typedef {Object} Options
- * @property {Array} items - the list of items that was used to generate the children of the given node (the list used in the #each block
+ * @property {Array<object>} items - the list of items that was used to generate the children of the given node (the list used in the #each block
  * @property {string} [type] - the type of the dnd zone. children dragged from here can only be dropped in other zones of the same type, default to a base type
  * @property {number} [flipDurationMs] - if the list animated using flip (recommended), specifies the flip duration such that everything syncs with it without conflict, defaults to zero
  * @property {boolean} [dragDisabled]
  * @property {boolean} [dropFromOthersDisabled]
- * @property {Object} [dragTargetStyle]
- * @property {Function} [transformDraggedElement]
+ * @property {Record<string, string>} [dragTargetStyle]
+ * @property {TransformDraggedElementFunc} [transformDraggedElement]
+ */
+
+/**
+ * @callback UpdateFunc
+ * @param {Options} newOptions
+ * @return {void}
+ */
+/**
+ * @callback DestroyFunc
+ * @return {void}
+ */
+
+// TODO - improve Info and check whether this needs 'detail', check how to make typescript export it
+/**
+ * @event DndEvent
+ * @type {object}
+ * @property {Array<object>} items
+ * @property {Info} info
+ */
+/**
+ * A custom action to turn any container to a dnd zone and all of its direct children to draggables
+ * Supports mouse, touch and keyboard interactions.
+ * Dispatches two events that the container is expected to react to by modifying its list of items,
+ * which will then feed back in to this action via the update function
+ *
  * @param {HTMLElement} node - the element to enhance
  * @param {Options} options
- * @return {{update: function, destroy: function}}
+ * @fires {DndEvent}
+ * @return {{update: UpdateFunc, destroy: DestroyFunc}}
  */
 export function dndzone(node, options) {
     validateOptions(options);
     const pointerZone = pointerDndZone(node, options);
     const keyboardZone = keyboardDndZone(node, options);
     return {
+        /** @type {UpdateFunc} update */
         update: newOptions => {
             validateOptions(newOptions);
             pointerZone.update(newOptions);
             keyboardZone.update(newOptions);
         },
+        /** @type {DestroyFunc} destroy */
         destroy: () => {
             pointerZone.destroy();
             keyboardZone.destroy();

src/helpers/dispatcher.js

@@ -8,7 +8,7 @@ const CONSIDER_EVENT_NAME = 'consider';
  * @property {string} id
  * @property {string} source
  * @param {Node} el
- * @param {Array} items
+ * @param {Array<object>} items
  * @param {Info} info
  */
 export function dispatchFinalizeEvent(el, items, info) {

src/helpers/styler.js

@@ -18,7 +18,6 @@ export function createDraggedElementFrom(originalElement) {
     const draggedEl = originalElement.cloneNode(true);
     copyStylesFromTo(originalElement, draggedEl);
     draggedEl.id = `dnd-action-dragged-el`;
-    draggedEl.name = `dnd-action-dragged-el`;
     draggedEl.style.position = "fixed";
     draggedEl.style.top = `${rect.top}px`;
     draggedEl.style.left = `${rect.left}px`;

tsconfig.json

@@ -0,0 +1,19 @@
+{
+  // Change this to match your project
+  "include": ["src/**/*"],
+
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // Types should go into this directory.
+    // Removing this would place the .d.ts files
+    // next to the .js files
+    "outDir": "types"
+  }
+}

yarn.lock

@@ -3241,6 +3241,13 @@ rollup-plugin-babel@^4.3.2:
     "@babel/helper-module-imports" "^7.0.0"
     rollup-pluginutils "^2.8.1"
 
+rollup-plugin-dts@^1.4.13:
+  version "1.4.13"
+  resolved "https://registry.yarnpkg.com/rollup-plugin-dts/-/rollup-plugin-dts-1.4.13.tgz#4f086e84f4fdcc1f49160799ebc66f6b09db292b"
+  integrity sha512-7mxoQ6PcmCkBE5ZhrjGDL4k42XLy8BkSqpiRi1MipwiGs+7lwi4mQkp2afX+OzzLjJp/TGM8llfe8uayIUhPEw==
+  optionalDependencies:
+    "@babel/code-frame" "^7.10.4"
+
 rollup-pluginutils@^2.8.1:
   version "2.8.2"
   resolved "https://registry.yarnpkg.com/rollup-pluginutils/-/rollup-pluginutils-2.8.2.tgz#72f2af0748b592364dbd3389e600e5a9444a351e"
@@ -3623,6 +3630,11 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=
 
+typescript@^4.0.3:
+  version "4.0.3"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.0.3.tgz#153bbd468ef07725c1df9c77e8b453f8d36abba5"
+  integrity sha512-tEu6DGxGgRJPb/mVPIZ48e69xCn2yRmCgYmDugAVwmJ6o+0u1RI18eO7E7WBTLYLaEVVOhwQmcdhQHweux/WPg==
+
 unicode-canonical-property-names-ecmascript@^1.0.4:
   version "1.0.4"
   resolved "https://registry.yarnpkg.com/unicode-canonical-property-names-ecmascript/-/unicode-canonical-property-names-ecmascript-1.0.4.tgz#2619800c4c825800efdd8343af7dd9933cbe2818"