{"_id":"@area17/flotsam-autocomplete","_rev":"1-b777e0ee997e048280b57bf69c6eb826","name":"@area17/flotsam-autocomplete","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@area17/flotsam-autocomplete","version":"1.0.0","description":"Accessibility first autocomplete without limiting style flexibility","type":"module","source":"src/index.js","exports":{"require":"./dist/flotsam.cjs","default":"./dist/flotsam.modern.js"},"main":"./dist/flotsam.cjs","module":"./dist/flotsam.module.js","unpkg":"./dist/flotsam.umd.js","scripts":{"build":"microbundle --css","dev":"microbundle watch --css"},"keywords":["autocomplete","auto complete","autocompelte","typeahead","type ahead","flotsam","flotsame","floatsome"],"repository":{"type":"git","url":"git+https://github.com/area17/flotsam.git"},"author":{"name":"A17","email":"dev@area17.com","url":"https://area17.com/"},"license":"MIT","bugs":{"url":"https://github.com/area17/flotsam/issues"},"homepage":"https://github.com/area17/flotsam#readme","devDependencies":{"microbundle":"^0.15.1"},"dependencies":{"prettier":"^2.8.3"},"gitHead":"33e0141a2b8cce926c2acc22a46f7398cbd6bbee","_id":"@area17/flotsam-autocomplete@1.0.0","_nodeVersion":"18.7.0","_npmVersion":"8.15.1","dist":{"integrity":"sha512-363D+aQEJrpnhBmLd9H6OqXtObcluCES1b9px8JicTHzPyaLPRbMWP2KU3Lk8jHPyHvxcgMTs86IyLmIVwyXQA==","shasum":"0d80b8cc014fb0dc4f1685452b237d1f0c725ce4","tarball":"https://registry.npmjs.org/@area17/flotsam-autocomplete/-/flotsam-autocomplete-1.0.0.tgz","fileCount":22,"unpackedSize":212727,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCICJ783Yye7ZqHBysOoH2HopPJ2jAVcisU0tg3zSkYsUjAiEAxLZVkDKfPYTkleYkWMQBa/NrhJ0cqDNchZ7wZ3wkBf4="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJj4+GEACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmq/bg//WT0Kei7WXFgjMXaWQWKlB2bqX7jgeLnuKQifoPPHilSwegIM\r\n3oO/n0XKOIDPs8wTL2lytGfRFPpQMG49g+g5HoK5UeOr6PH1yY72CXjbd1T/\r\nA5PrVXUPVGe/m8cka7DpwlVe52ZKVWB+IpDKr0OujubMIoPAFLkQ3Z+Ssmw+\r\ntCWWv61unTLHGfxAtuAxYcy9gGBsrErij3OxdILZtS8rHc3SmVK+e44Nusmq\r\nk9SWs6C39tNCNB3RmEnmwHEtUyS2ENP0o8/99R1etcvT4QC/IF+gay7l/dbN\r\nGWZzYrxTa8c0hiYLAuZR+fBFYDr+6ltJp2FuTZThYXr1/rqtMGxHjVt8hCdI\r\n0cGaX19VclAvwKorGnBFAtSIFC0oeSPbekE98mV1txfuEIJRPFEcTavHpp2U\r\nQdyPn3ouP/End6HuiNyKpjtUsuM10V/d8ZAvZBiO+VKiBwrwGUVLZxOTCb7l\r\nnxrXfgPT35ikYsVmqC4XO5fBpLLP8cQMJ5Ifk8OoHLABLVjMjqCYkS64i5x5\r\n1PtulM9BQZxM5kYRkeB6L1kkxGPnolt419OtyfDcNI0K9xdWPxAAD+oaZKZg\r\nRbbv3ugVonkVlbmeSgrOfmzmFnGA/X9cPgV7XyomQ7OPDRiiEnzQZMr4+/Fn\r\n3mLS1fzyV4yqjP1sUwuktOy/UtW69jciw1c=\r\n=7rtq\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"13twelve","email":"mike@thirteentwelve.com"},"directories":{},"maintainers":[{"name":"13twelve","email":"mike@thirteentwelve.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/flotsam-autocomplete_1.0.0_1675878788622_0.1573284482548154"},"_hasShrinkwrap":false}},"time":{"created":"2023-02-08T17:53:08.568Z","1.0.0":"2023-02-08T17:53:08.759Z","modified":"2023-02-08T17:53:47.445Z"},"maintainers":[{"email":"mike@thirteentwelve.com","name":"13twelve"},{"email":"patrick@croustille.io","name":"ptrckvzn"},{"email":"quentin@area17.com","name":"quentinrenard"},{"email":"antoine@area17.com","name":"mrdoinel"},{"email":"antonin.caudron@gmail.com","name":"m4n1ok"},{"email":"ewomaukah@yahoo.com","name":"mazinoukah"},{"email":"tim@area17.com","name":"mrtimbrook"}],"description":"Accessibility first autocomplete without limiting style flexibility","homepage":"https://github.com/area17/flotsam#readme","keywords":["autocomplete","auto complete","autocompelte","typeahead","type ahead","flotsam","flotsame","floatsome"],"repository":{"type":"git","url":"git+https://github.com/area17/flotsam.git"},"author":{"name":"A17","email":"dev@area17.com","url":"https://area17.com/"},"bugs":{"url":"https://github.com/area17/flotsam/issues"},"license":"MIT","readme":"# Flotsam autocomplete\n\n/ˈflätsəm/\n\n_noun_\n\n-   the wreckage of a ship or its cargo found floating on or washed up by the sea.\n-   people or things that have been rejected and are regarded as worthless.\n-   An a11y autocomplete library\n\n---\n\n## Mission Statement\n\nWe felt that the existing choices for typeahead/autocomplete UI are lacking one or more in the following areas:\n\n-   vetted accessibility standards\n-   simplicity, with clear documentation\n-   a modern event bus system\n-   flexible styling\n-   vanilla JS with no requirement for jQuery,\n-   small footprint (<4kb)\n\nThis library is inspired and aims to build upon [alphagov/accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete).\n\n---\n\n## Demo\n\n[http://flotsam.dev.area17.com/](http://flotsam.dev.area17.com/)\n\n---\n\n## Using Flotsam\n\nFirstly, install via npm:\n\n```\n$ npm install flotsam-autocomplete\n```\n\nImport into your JavaScript by:\n\n```\nimport flotsam from 'flotsam-autocomplete'\n```\n\nYou'll also need some very basic styles - see [Styling](#styling).\n\n### Static setup\n\n\n```JavaScript\nconst typeahead = new flotsam({\n    // input element you want to attach to\n    el: document.querySelector('input'),\n    // static data formatted in an array, this is the data that will render on interaction\n    data: ['lorem ipsum', 'lipsum', 'hello world', 'foo', 'bar', 'foo bar'],\n});\n```\n\n**NB** currently filtering from a static list uses `[String.prototype.includes()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes)` and so looks for exact string matches - e.g. \"and\" will match \"and\", \"stand\", \"mandatory\" etc.\n \n### Dynamic setup\n\n```JavaScript\nlet fetchController = new AbortController();\nlet fetchSignal = fetchController.signal;\n\nconst typeahead = new flotsam({\n    // input element you want to attach to\n    el: document.querySelector('input'),\n\n    // textValue is the input/search value \n    getData: (textValue) => {\n        fetchController.abort();\n        fetchController = new AbortController();\n        fetchSignal = fetchController.signal;\n\n        const url = new URL('http://fakejsonendpoints.dev.area17.com/api/autocomplete.php');\n        const params = {\n          q: textValue,\n        };\n        url.search = new URLSearchParams(params).toString();\n\n        return fetch(\n          url, \n          {\n            method: 'get',\n            signal: fetchSignal,\n            headers: {\n              \"Content-Type\": \"application/json\",\n              \"Accept\": \"application/json\",\n              \"X-Requested-With\": \"XMLHttpRequest\",\n            }\n          }\n        )\n        .then(response => {\n          try {\n            return response.json();\n          } catch(error) {\n            console.log('json error:', error, response);\n          }\n        })\n        .then(data => {\n          // return data arr\n          return data;\n        })\n        .catch(error => {\n          console.log('fetch error:', error);\n          return [];\n        });\n    }\n});\n```\n\n**NB** Your Ajax'd list should be filtered by your remote server, so you can allow fuzzy or exact string matches\n\n#### Options\n\n```JavaScript\nconst typeahead = new flotsam({\n    el: document.querySelector('input'),\n    data: [...data],\n\n    // this sets the minimum count of input characters before we will render the box, defaults to 2\n    minChars: 2,\n\n    // when key-ing up or down, the input will fill with the previewed string\n    // defaults to true\n    inputPreview: true,\n\n    // a11y instructions, defaults to:\n    hint: 'When autocomplete results are available, use up and down arrows to review and enter to select. Touch device users, explore by touch or with swipe gestures.',\n\n    // no results text, `::term::` is replaced with your search term\n    noResultsText: 'Sorry there are no results for ::term:: please search again',\n\n    // mark results in results, with `<mark>` tags, defaults to `true`\n    markResults: true,\n\n    // submit form on return key press, defaults to `true`\n    submitOnReturn: true,\n})\n```\n\n### Events\n\nFlotsom triggers events on user interaction:\n\n```JavaScript\nconst typeahead = new flotsam({\n    el: document.querySelector('input'),\n    data: [...data],\n});\n\ntypeahead.addEventListener('init', instanceData => {\n    // flotsam init\n});\n\ntypeahead.addEventListener('openModal', (instanceData) => {\n    // modal opened\n});\n\ntypeahead.addEventListener('closeModal', (instanceData) => {\n    // modal closed\n});\n\ntypeahead.addEventListener('selectKey', (instanceData) => {\n    // selected item (with keyboard)\n});\n\ntypeahead.addEventListener('resultClicked', (instanceData) => {\n    // result clicked/return key pressed on selected result\n});\n\ntypeahead.addEventListener('loadingData', (instanceData) => {\n    // loading data\n});\n\ntypeahead.addEventListener('loadedData', (instanceData) => {\n    // loaded\n});\n\ntypeahead.addEventListener('disabled', (instanceData) => {\n    // flotsam disabled\n});\n```\n\n`InstanceData` has access to the current, modal, input, options (readonly), and any other useful information i could think of!\n\n### Methods\n\n```JavaScript\nconst typeahead = new flotsam({\n    el: document.querySelector('input'),\n    data: [...data],\n});\n\n// force close the flotsom\ntypeahead.triggerClose();\n\n// enables flotsom\ntypeahead.triggerEnable();\n\n// disables flotsom\ntypeahead.triggerDisable();\n```\n\n### Keyboard controls\n\nFlotsom includes keyboard controls which follow the google autocomplete UI:\n\n-   `Arrow Up` and `Arrow Down` keys allow you to select previous and next items while open\n-   `Tab` will set the value, close the modal, but NOT submit (google-like)\n-   `Escape` will set the value, close the modal, but NOT submit (google-like)\n-   `Enter` will set the value, close the modal AND submit (google-like)\n\n---\n\n## Styling\n\nThe rendered HTML will look like:\n\n```HTML\n<div class=\"flotsam-modal\">\n    <div class=\"flotsam-modal__inner\">\n        <ul class=\"flotsam-modal__list\" role=\"combobox\">\n            <li role=\"option\" class=\"flotsam-modal__list-item flotsam-modal__selected-item\">Rendered value 1 (selected)</li>\n            <li role=\"option\" class=\"flotsam-modal__list-item\"><mark>Rendered value 2 (highlighted)</mark></li>\n            <li role=\"option\" class=\"flotsam-modal__list-item\">Rendered value 3</li>\n        </ul>\n    </div>\n</div>\n<div id=\"assistiveHint-${this.uid}\" class=\"flotsam-modal__hint\">When autocomplete results are available, use up and down arrows to review and enter to select. Touch device users, explore by touch or with swipe gestures.</div>\n<div id=\"status-${this.uid}\" aria-role='status' aria-live=\"polite\" class=\"flotsam-modal__status\"></div>\n```\n\nThe container of your `input` will need to have `position: relative;` in order to correctly position the dropdown.\n\nSome default styles can be included by importing:\n\n```\nimport './node_modules/flotsam-autocomplete/dist/flotsam.css'\n```\n\nThese default styles come with colors set via CSS variables:\n\n```CSS\n:root {\n    --flotsam-border: black;\n    --flotsam-selected: pink;\n    --flotsam-empty: grey;\n}\n```\n\nThese default styles really are basic:\n\n```CSS\n.flotsam-modal {\n    position: absolute;\n    width: 100%;\n    top: 100%;\n    border: 1px solid var(--flotsam-border, black);\n}\n\n.flotsam-modal__inner {\n    padding: 0 24px;\n    max-height: 200px;\n    overflow: scroll;\n}\n\n.flotsam-modal__list .flotsam-modal__selected-item {\n    background: var(--flotsam-selected, pink);\n}\n\n.flotsam-modal__empty {\n    max-height: 200px;\n    padding: 25px;\n    color: var(--flotsam-empty, grey);\n    font-size: 14px;\n}\n\n.flotsam-modal__hint,\n.flotsam-modal__status {\n    clip: rect(0 0 0 0);\n    clip-path: inset(50%);\n    height: 1px;\n    overflow: hidden;\n    position: absolute;\n    white-space: nowrap;\n    width: 1px;\n}\n```\n\nYou will likely want to replace and write your own, but the imported styles will hopefully get you set up and started.\n\n## Roadmap\n\n-   100% a11y parity with [alphagov/accessible-autocomplete](https://github.com/alphagov/accessible-autocomplete)\n-   Custom empty state option\n-   Assistive text for screen readers (using `aria-describeby`)\n-   Optional empty state modal\n-   Outside click close (with option to disable that)\n-   Keep the project small in size\n\n### Nice to haves\n\n-   Custom filterBy and sortBy functions before we generate autocomplete list items\n-   Custom regex for the text highlight on autocomplete \n\n---\n\n## Code of Conduct\n\nAREA 17 is dedicated to building a welcoming, diverse, safe community. We expect everyone participating in the AREA 17 community to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please read it. Please follow it.\n","readmeFilename":"README.md"}