[doc] add documentation of using Draggable with TypeScript

README.md

@@ -126,6 +126,12 @@ You can find the documentation for each module within their respective directori
 - [Swappable](src/Swappable)
   - [SwappableEvent](src/Swappable/SwappableEvent)
 
+## TypeScript
+
+Draggable includes [TypeScript](http://typescriptlang.org) definitions.
+
+[Documentation](doc/typescript.md)
+
 ## Running examples
 
 To run the `examples` project locally, simply run the following from the `draggable` root:

doc/typescript.md

@@ -0,0 +1,51 @@
+# Default usage
+
+```typescript
+import {Sortable} from '@shopify/draggable';
+
+const sortable = new Sortable(document.querySelectorAll('ul'), {
+  draggable: 'li',
+});
+
+// The type of the first argument is SortableEventNames
+sortable.on('sortable:sort', (evt) => {
+  // The type of evt is SortableSortEvent
+});
+
+// The type of the first argument is SortableEventNames
+sortable.on('drag:out:container', (evt) => {
+  // The type of evt is DragOutContainerEvent
+});
+```
+
+# Using plugins
+
+When creating an instance with plugins with events, you need to manually specify the event names.
+
+```typescript
+import {Droppable, Plugins} from '@shopify/draggable';
+
+// 1. import the event names you need
+import type {
+  DroppableEventNames,
+  CollidableEventNames,
+} from "@shopify/draggable";
+
+// 2. Specify the event names when create the instance
+const droppable = new Droppable<DroppableEventNames | CollidableEventNames>(document.querySelectorAll('.container'), {
+  draggable: '.item',
+  dropzone: '.dropzone',
+  collidables: '.other-list',
+  plugins: [Plugins.Collidable],
+});
+
+// The type of the first argument can be DroppableEventNames or CollidableEventNames
+droppable.on('droppable:dropped', (evt) => {
+  // The type of evt is DroppableDroppedEvent
+});
+
+// The type of the first argument can be DroppableEventNames or CollidableEventNames
+droppable.on('collidable:in', (evt) => {
+  // The type of evt is CollidableInEvent
+});
+```