From 05b033c1014ff8f10f41663ec13820909fd055b9 Mon Sep 17 00:00:00 2001 From: Wayne Van Son Date: Fri, 25 Oct 2019 04:41:30 +1100 Subject: [PATCH] [sortablejs] adds all options, plugins and mount function (#39049) * adds wayne as definition contributer * fixes GroupOptions 'pull' and 'put' types * [fix] renames Group to GroupOptions * removes AutoScroll options from SortableOptions, Options extends SortableOptions * adds options for autoscroll, onspill and multidrag * adds SwapOptions * adds sortable.mount function with `any` type * adds all available plugins and uses SortablePlugin type on Sortable.mount() * adds plugins.d.ts to tsconfig * [fix] makes all options from the plugins optional * [tests] fixes sortable.group.put type; is string[], not string * [tests] adds tests for mounting plugins * adds examples to sortable.mount * [format] reverts formatting in test file * adds options as options for sortable constructor * change removeonclonehide to boolean from true --- types/sortablejs/index.d.ts | 143 ++++++++++++++++++++++----- types/sortablejs/plugins.d.ts | 92 +++++++++++++++++ types/sortablejs/sortablejs-tests.ts | 7 +- types/sortablejs/tsconfig.json | 3 +- 4 files changed, 219 insertions(+), 26 deletions(-) create mode 100644 types/sortablejs/plugins.d.ts diff --git a/types/sortablejs/index.d.ts b/types/sortablejs/index.d.ts index cb69f765fd..a364531f24 100644 --- a/types/sortablejs/index.d.ts +++ b/types/sortablejs/index.d.ts @@ -1,9 +1,21 @@ -// Type definitions for Sortable.js 1.7 +// Type definitions for Sortable.js 1.10 // Project: https://github.com/RubaXa/Sortable // Definitions by: Maw-Fox // Maarten Staa +// Wayne Van Son // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped // TypeScript Version: 2.1 +import { + AutoScrollOptions, + MultiDragOptions, + OnSpillOptions, + SwapOptions, + AutoScrollPlugin, + MultiDragPlugin, + OnSpillPlugin, + SwapPlugin, + SortablePlugin, +} from './plugins'; export = Sortable; @@ -21,12 +33,22 @@ declare class Sortable { static active: Sortable; static utils: Sortable.Utils; + /** + * Mounts a plugin to Sortable + * @param sortablePlugin a sortable plugin. + * + * @example + * + * Sortable.mount(new MultiDrag(), new AutoScroll()) + */ + static mount(...sortablePlugins: SortablePlugin[]): void; + /** * Creation of new instances. * @param element Any variety of HTMLElement. * @param options Sortable options object. */ - static create(element: HTMLElement, options: Sortable.Options): Sortable; + static create(element: HTMLElement, options?: Sortable.Options): Sortable; /** * Options getter/setter @@ -66,6 +88,18 @@ declare class Sortable { } declare namespace Sortable { + export interface Options + extends SortableOptions, + AutoScrollOptions, + MultiDragOptions, + OnSpillOptions, + SwapOptions {} + + export class MultiDrag extends MultiDragPlugin {} + export class AutoScroll extends AutoScrollPlugin {} + export class Swap extends SwapPlugin {} + export class OnSpill extends OnSpillPlugin {} + export interface SortableEvent extends Event { clone: HTMLElement; /** @@ -104,6 +138,8 @@ declare namespace Sortable { willInsertAfter?: boolean; } + type PullResult = ReadonlyArray | boolean | 'clone'; + type PutResult = ReadonlyArray | boolean; export interface GroupOptions { /** * group name @@ -112,18 +148,18 @@ declare namespace Sortable { /** * ability to move from the list. clone — copy the item, rather than move. */ - pull?: boolean | 'clone' | ((to: Sortable, from: Sortable) => boolean | string); + pull?: PullResult | ((to: Sortable, from: Sortable) => PullResult); /** * whether elements can be added from other lists, or an array of group names from which elements can be taken. */ - put?: boolean | string | ReadonlyArray | ((to: Sortable) => boolean); + put?: ((to: Sortable) => PutResult) | PutResult; /** * revert cloned element to initial position after moving to a another list. */ revertClone?: boolean; } - - export interface Options { + type Direction = 'vertical' | 'horizontal'; + export interface SortableOptions { /** * ms, animation speed moving items when sorting, `0` — without animation */ @@ -137,6 +173,15 @@ declare namespace Sortable { * time in milliseconds to define when the sorting should start */ delay?: number; + /** + * Only delay if user is using touch + */ + delayOnTouchOnly?: boolean; + /** + * Direction of Sortable + * (will be detected automatically if not given) + */ + direction?: ((evt: SortableEvent, target: HTMLElement, dragEl: HTMLElement) => Direction) | Direction; /** * Disables the sortable if set to true. */ @@ -151,6 +196,38 @@ declare namespace Sortable { draggable?: string; dragoverBubble?: boolean; dropBubble?: boolean; + /** + * distance mouse must be from empty sortable + * to insert drag element into it + */ + emptyInsertThreshold?: number; + + /** + * Easing for animation. Defaults to null. + * + * See https://easings.net/ for examples. + * + * For other possible values, see + * https://www.w3schools.com/cssref/css3_pr_animation-timing-function.asp + * + * @example + * + * // CSS functions + * | 'steps(int, start | end)' + * | 'cubic-bezier(n, n, n, n)' + * + * // CSS values + * | 'linear' + * | 'ease' + * | 'ease-in' + * | 'ease-out' + * | 'ease-in-out' + * | 'step-start' + * | 'step-end' + * | 'initial' + * | 'inherit' + */ + easing?: string; /** * Class name for the cloned DOM Element when using forceFallback */ @@ -163,11 +240,13 @@ declare namespace Sortable { * Specify in pixels how far the mouse should move before it's considered as a drag. */ fallbackTolerance?: number; - fallbackOffset?: { x: number, y: number }; + fallbackOffset?: { x: number; y: number }; /** * Selectors that do not lead to dragging (String or Function) */ - filter?: string | ((this: Sortable, event: Event | TouchEvent, target: HTMLElement, sortable: Sortable) => boolean); + filter?: + | string + | ((this: Sortable, event: Event | TouchEvent, target: HTMLElement, sortable: Sortable) => boolean); /** * ignore the HTML5 DnD behaviour and force the fallback to kick in */ @@ -186,23 +265,24 @@ declare namespace Sortable { */ handle?: string; ignore?: string; + /** + * Will always use inverted swap zone if set to true + */ + invertSwap?: boolean; + /** + * Threshold of the inverted swap zone + * (will be set to `swapThreshold` value by default) + */ + invertedSwapThreshold?: number; /** * Call `event.preventDefault()` when triggered `filter` */ preventOnFilter?: boolean; - scroll?: boolean; /** - * if you have custom scrollbar scrollFn may be used for autoscrolling + * Remove the clone element when it is not showing, + * rather than just hiding it */ - scrollFn?: ((this: Sortable, offsetX: number, offsetY: number, event: MouseEvent) => void); - /** - * px, how near the mouse must be to an edge to start scrolling. - */ - scrollSensitivity?: number; - /** - * px - */ - scrollSpeed?: number; + removeCloneOnHide?: boolean; /** * sorting inside list */ @@ -211,6 +291,16 @@ declare namespace Sortable { get: (sortable: Sortable) => string[]; set: (sortable: Sortable) => void; }; + /** + * Threshold of the swap zone. + * Defaults to `1` + */ + swapThreshold?: number; + /** + * How many *pixels* the point should move before cancelling a delayed drag event + */ + touchStartThreshold?: number; + setData?: (dataTransfer: DataTransfer, draggedElement: HTMLElement) => void; /** * Element dragging started @@ -254,11 +344,12 @@ declare namespace Sortable { onFilter?: (event: SortableEvent) => void; /** * Event when you move an item in the list or between lists - * return false; for cancel - * return -1; insert before target - * return 1; insert after target */ - onMove?: (event: MoveEvent, originalEvent: MouseEvent) => false | -1 | 1; + onMove?: (evt: MoveEvent, originalEvent: Event) => boolean | -1 | 1; + /** + * Called when dragging element changes position + */ + onChange?: (evt: SortableEvent) => void; } interface Utils { @@ -305,7 +396,11 @@ declare namespace Sortable { * @param tagName A tag name. * @param iterator An iterator. */ - find(context: HTMLElement, tagName: string, iterator?: (value: HTMLElement, index: number) => void): NodeListOf; + find( + context: HTMLElement, + tagName: string, + iterator?: (value: HTMLElement, index: number) => void, + ): NodeListOf; /** * Check the current matched set of elements against a selector. diff --git a/types/sortablejs/plugins.d.ts b/types/sortablejs/plugins.d.ts new file mode 100644 index 0000000000..4d2c8b1ce8 --- /dev/null +++ b/types/sortablejs/plugins.d.ts @@ -0,0 +1,92 @@ +import * as Sortable from './index'; +import { SortableEvent } from './index'; + +declare class SortablePlugin {} +declare class AutoScrollPlugin {} +declare class OnSpillPlugin {} +declare class MultiDragPlugin {} +declare class SwapPlugin {} + +export interface AutoScrollOptions { + /** + * Enable the plugin. Can be `HTMLElement`. + */ + scroll?: boolean | HTMLElement; + /** + * if you have custom scrollbar scrollFn may be used for autoscrolling. + */ + scrollFn?: ( + this: Sortable, + offsetX: number, + offsetY: number, + originalEvent: Event, + touchEvt: TouchEvent, + hoverTargetEl: HTMLElement, + ) => 'continue' | void; + /** + * `px`, how near the mouse must be to an edge to start scrolling. + */ + scrollSensitivity?: number; + /** + * `px`, speed of the scrolling.` + */ + scrollSpeed?: number; + /** + * apply autoscroll to all parent elements, allowing for easier movement. + */ + bubbleScroll?: boolean; +} +export interface OnSpillOptions { + /** + * This plugin, when enabled, + * will cause the dragged item to be reverted to it's original position if it is *spilled* + * (ie. it is dropped outside of a valid Sortable drop target) + */ + revertOnSpill?: boolean; + /** + * This plugin, when enabled, + * will cause the dragged item to be removed from the DOM if it is *spilled* + * (ie. it is dropped outside of a valid Sortable drop target) + */ + removeOnSpill?: boolean; + /** + * Called when either `revertOnSpill` or `RemoveOnSpill` plugins are enabled. + */ + onSpill?: (evt: SortableEvent) => void; +} +export interface MultiDragOptions { + /** + * Enable the plugin + */ + multiDrag?: boolean; + /** + * Class name for selected item + */ + selectedClass?: string; + /** + * Key that must be down for items to be selected + */ + // todo: create a type + // todo: check source code for type + multiDragKey?: null; + + /** + * Called when an item is selected + */ + onSelect?: (event: SortableEvent) => void; + + /** + * Called when an item is deselected + */ + onDeselect?: (event: SortableEvent) => void; +} +export interface SwapOptions { + /** + * Enable swap mode + */ + swap?: boolean; + /** + * Class name for swap item (if swap mode is enabled) + */ + swapClass?: string; +} diff --git a/types/sortablejs/sortablejs-tests.ts b/types/sortablejs/sortablejs-tests.ts index f277e2a638..0cf7143e43 100644 --- a/types/sortablejs/sortablejs-tests.ts +++ b/types/sortablejs/sortablejs-tests.ts @@ -324,7 +324,7 @@ Sortable.create(simpleList, { Sortable.create(simpleList, { group: { name: 'bar', - put: 'qux', + put: ['qux'], pull: function (to, from) { return from.el.children.length > 2 || 'clone'; } @@ -370,3 +370,8 @@ Sortable.create(simpleList, { return 1; // insert after target } }); + +// plugins +const { AutoScroll, MultiDrag, OnSpill, Swap } = Sortable; +Sortable.mount(new AutoScroll(), new MultiDrag(), new OnSpill(), new Swap()); +Sortable.mount(new MultiDrag()); diff --git a/types/sortablejs/tsconfig.json b/types/sortablejs/tsconfig.json index 753fea5190..ecb500b45e 100644 --- a/types/sortablejs/tsconfig.json +++ b/types/sortablejs/tsconfig.json @@ -19,6 +19,7 @@ }, "files": [ "index.d.ts", - "sortablejs-tests.ts" + "sortablejs-tests.ts", + "plugins.d.ts" ] }