From 57ea442f2a2c9065f51b7923f810a5da4792d4e6 Mon Sep 17 00:00:00 2001 From: Isaac Hagoel Date: Wed, 14 Oct 2020 13:42:21 +1100 Subject: [PATCH] 143 - experiment - improved jsdoc and exported to a type definition file --- .gitignore | 1 + package.json | 9 ++++--- rollup.config.js | 9 +++++-- src/action.js | 49 ++++++++++++++++++++++++++++++++------- src/helpers/dispatcher.js | 2 +- src/helpers/styler.js | 1 - tsconfig.json | 19 +++++++++++++++ yarn.lock | 12 ++++++++++ 8 files changed, 86 insertions(+), 16 deletions(-) create mode 100644 tsconfig.json diff --git a/.gitignore b/.gitignore index 00ad51b..d88fe90 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ *.iml node_modules /dist/ +/types/ cypress/videos cypress/screenshots diff --git a/package.json b/package.json index 7d3a57c..42326d8 100644 --- a/package.json +++ b/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", diff --git a/rollup.config.js b/rollup.config.js index ace4e30..e39589a 100644 --- a/rollup.config.js +++ b/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() ] -}; \ No newline at end of file +}, { + input: "./types/index.d.ts", + output: [{ file: "dist/index.d.ts", format: "es" }], + plugins: [dts()], +}]; \ No newline at end of file diff --git a/src/action.js b/src/action.js index 4fd60a5..d8dbeb8 100644 --- a/src/action.js +++ b/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} 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} [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} 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(); diff --git a/src/helpers/dispatcher.js b/src/helpers/dispatcher.js index 7432c37..f80e262 100644 --- a/src/helpers/dispatcher.js +++ b/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} items * @param {Info} info */ export function dispatchFinalizeEvent(el, items, info) { diff --git a/src/helpers/styler.js b/src/helpers/styler.js index 2f93f19..15731df 100644 --- a/src/helpers/styler.js +++ b/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`; diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..4447e1a --- /dev/null +++ b/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" + } +} diff --git a/yarn.lock b/yarn.lock index b0222a8..7ce8c78 100644 --- a/yarn.lock +++ b/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"