{"id":20519758,"url":"https://github.com/placemark/flat-drop-files","last_synced_at":"2026-03-14T16:35:06.494Z","repository":{"id":37244539,"uuid":"452378727","full_name":"placemark/flat-drop-files","owner":"placemark","description":"Normalize the DataTransferItems interface from a drop event","archived":false,"fork":false,"pushed_at":"2022-12-27T14:01:49.000Z","size":105,"stargazers_count":164,"open_issues_count":2,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T16:11:13.995Z","etag":null,"topics":["datatransfer","drag-and-drop"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/placemark.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-26T17:45:36.000Z","updated_at":"2025-02-11T04:55:32.000Z","dependencies_parsed_at":"2023-01-31T03:25:13.883Z","dependency_job_id":null,"html_url":"https://github.com/placemark/flat-drop-files","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/placemark%2Fflat-drop-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/placemark%2Fflat-drop-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/placemark%2Fflat-drop-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/placemark%2Fflat-drop-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/placemark","download_url":"https://codeload.github.com/placemark/flat-drop-files/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248809051,"owners_count":21164896,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["datatransfer","drag-and-drop"],"created_at":"2024-11-15T22:15:59.426Z","updated_at":"2025-10-18T05:31:51.078Z","avatar_url":"https://github.com/placemark.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @placemarkio/flat-drop-files\n\nThe Drag \u0026 Drop [dataTransfer](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer)\ninterface is powerful, but torturous. It has grown organically and via standards,\nand is full of [footguns](https://www.wordsense.eu/footguns/) which make it trivially\neasy to mess up.\n\nThis is an attempt to make it all \"just work.\" The input is a `dataTransfer.items`\nlist, and the output is a normalized list of files, with a `handle` property\nthat's a [FileSystemFileHandle](https://developer.mozilla.org/en-US/docs/Web/API/FileSystemFileHandle),\nand a `path` property that's a reconstructed relative file path.\n\nThis module takes care of:\n\n- Recursively collecting files within directories\n- Reassembling paths of nested files\n- Paging through directories with over 100 files\n- Ignoring [junk](https://github.com/sindresorhus/junk) files like `.DS_Store`\n\nThis is at the bleeding edge of the web, so there are some caveats.\n\n- TypeScript does not support `FileSystemFileHandle` objects yet. This module\n  includes the `@types/wicg-file-system-access` module to polyfill that type until\n  it is properly introduced.\n  \n### Installation\n\nThis module is [published on npm as @placemarkio/flat-drop-files](https://www.npmjs.com/package/@placemarkio/flat-drop-files).\n\n### Example\n\n```ts\nimport { getFilesFromDataTransferItems } from \"@placemarkio/flat-drop-files\";\n\nconst zone = document.getElementById('zone');\n\nzone.addEventListener(\"dragenter\", (e) =\u003e {\n  e.preventDefault();\n});\n\nzone.addEventListener(\"dragover\", (e) =\u003e {\n  e.preventDefault();\n});\n\nzone.addEventListener(\"drop\", (e) =\u003e {\n  e.preventDefault();\n  getFilesFromDataTransferItems(e.dataTransfer.items).then(files =\u003e {\n    console.log(files);\n  });\n});\n```\n\n### Compatibility\n\nThis module is compatible with modern browsers: the baseline is browsers\nthat support [webkitGetAsEntry](https://caniuse.com/mdn-api_datatransferitem_webkitgetasentry).\nIt does not support IE11 or any other ancient browsers.\n\n### Ecosystem\n\nThe [browser-fs-access](https://github.com/GoogleChromeLabs/browser-fs-access) module\nis highly recommended to work with the file objects returned by this module:\nwith it, you can write back to the files using the `file.handle` property.\n\n### Source\n\nThis is inspired by [datatransfer-files-promise](https://github.com/anatol-grabowski/datatransfer-files-promise),\ncontains collected lessons from [dropzone](https://github.com/dropzone/dropzone),\nand adapts its junk-file detection from Sindre Sorhus's excellent [junk](https://github.com/sindresorhus/junk) module.\n\n### Testing\n\nThis kind of module is exceptionally hard to test with automated tests. Thus, there's a manual test suite. Start the\ntest suite with `yarn start`, which will boot up a local server, and follow the instructions, which involve dragging \u0026 dropping\nparticular files and folders into the browser.\n\n### Comments\n\nYou'll find plenty of comments in `index.ts` about different gotchas and traps in the DataTransferItem, FileSystemEntry, and other APIs. It's unfortunately easy to get these things wrong, whether it's assuming that [DataTransferItem.kind](https://developer.mozilla.org/en-US/docs/Web/API/DataTransferItem/kind) will correctly identify a directory, or forgetting to call `readEntries` on a directory reader repeatedly to page through each 100-item batch of files.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplacemark%2Fflat-drop-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplacemark%2Fflat-drop-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplacemark%2Fflat-drop-files/lists"}