diff --git a/README.md b/README.md index 088fca4..46b264d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -lite-emoji-picker +emoji-picker-element ==== -A small, performant, accessible emoji picker, distributed as a web component. +A small, performant, accessible emoji picker, distributed as a custom element. It's built on top of IndexedDB, so it consumes far less memory than other emoji pickers. It also uses [Svelte](https://svelte.dev), so it has a minimal runtime footprint. @@ -14,35 +14,35 @@ Design goals: ## Install - npm install lite-emoji-picker + npm install emoji-picker-element ## Usage ```html - + ``` ```js -import 'lite-emoji-picker'; +import 'emoji-picker-element'; ``` -`lite-emoji-picker` will expand to fit whatever container you give it. Here is a good default: +`emoji-picker-element` will expand to fit whatever container you give it. Here is a good default: ```css -lite-emoji-picker { +emoji-picker { width: 400px; height: 300px; } ``` -`lite-emoji-picker` uses Shadow DOM, so its inner styling is not accessible except via the API. +`emoji-picker-element` uses Shadow DOM, so its inner styling is not accessible except via the API. ## API ### Picker ```js -import { Picker } from 'lite-emoji-picker'; +import { Picker } from 'emoji-picker-element'; const picker = new Picker(); document.body.appendChild(picker); ``` @@ -51,9 +51,9 @@ document.body.appendChild(picker); | Option | Type | Default | Description | | ------ | ---- | ------- | ----------- | -| `dataSource` | String | `"https://cdn.jsdelivr.net/npm/emojibase-data@5/en/data.json"` | Where to fetch the emoji data from. Note that `lite-emoji-picker` requires the full `data.json`, not `compact.json`. | +| `dataSource` | String | `"https://cdn.jsdelivr.net/npm/emojibase-data@5/en/data.json"` | Where to fetch the emoji data from. Note that `emoji-picker-element` requires the full `data.json`, not `compact.json`. | | `locale` | String | `"en"` | Locale, should map to the locales supported by `emojibase-data` | -| `i18n` | Object | See below | Strings to use for internationalization of the Picker itself, i.e. the text and `aria-label`s. Note that `lite-emoji-picker` only ships with English by default. | +| `i18n` | Object | See below | Strings to use for internationalization of the Picker itself, i.e. the text and `aria-label`s. Note that `emoji-picker-element` only ships with English by default. | These values can also be set at runtime, e.g.: @@ -90,11 +90,11 @@ Note that some of these values are only visible to users of screen readers (but ##### Dark mode -By default, `lite-emoji-picker` will automatically switch to dark mode based on [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). For more fine-grained, control, add the class `dark` or `light` to force dark/light mode: +By default, `emoji-picker-element` will automatically switch to dark mode based on [`prefers-color-scheme`](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). For more fine-grained, control, add the class `dark` or `light` to force dark/light mode: ```html - - + + ``` ###### CSS variables @@ -108,7 +108,7 @@ Many attributes such as colors and sizes can be styled with CSS variables. Here For example: ```css -lite-emoji-picker { +emoji-picker { --num-columns: 6; --emoji-size: 3rem; --background-color: gray; @@ -120,7 +120,7 @@ lite-emoji-picker { You can work with the database API separately: ```js -import { Database } from 'lite-emoji-picker'; +import { Database } from 'emoji-picker-element'; const database = new Database(); await database.getEmojiBySearchPrefix('elephant'); // [{unicode: "🐘", ...}] @@ -144,15 +144,15 @@ In general, it's not a problem to create multiple `Database` objects with the sa If you want to import the `Database` without the `Picker`, or you want to import them separately, then do: ```js -import Picker from 'lite-emoji-picker/picker'; -import Database from 'lite-emoji-picker/database'; +import Picker from 'emoji-picker-element/picker'; +import Database from 'emoji-picker-element/database'; ``` The reason for this is that `Picker` automatically registers itself as a custom element, following [web component best practices](https://justinfagnani.com/2019/11/01/how-to-publish-web-components-to-npm/). But this adds side effects, so bundlers do not tree-shake as well unless the modules are imported from completely separate files. ## Focus outline -By default, `lite-emoji-picker` displays a prominent focus ring for accessibility reasons. If you want to hide the focus ring for non-keyboard users (e.g. mouse and touch only), then use the [focus-visible](https://github.com/WICG/focus-visible) polyfill, e.g.: +By default, `emoji-picker-element` displays a prominent focus ring for accessibility reasons. If you want to hide the focus ring for non-keyboard users (e.g. mouse and touch only), then use the [focus-visible](https://github.com/WICG/focus-visible) polyfill, e.g.: ```css .js-focus-visible :focus:not(.focus-visible) { @@ -167,13 +167,13 @@ const picker = new Picker(); applyFocusVisiblePolyfill(picker.shadowRoot); ``` -`lite-emoji-picker` already ships with the proper CSS for both the `:focus_visible` standard and the polyfill. +`emoji-picker-element` already ships with the proper CSS for both the `:focus_visible` standard and the polyfill. ## Data and offline ### Data source and JSON format -`lite-emoji-picker` requires the _full_ [emojibase-data](https://github.com/milesj/emojibase) JSON file, not the "compact" one. If you would like to trim the JSON file down even further, then modify the file to only contain these keys: +`emoji-picker-element` requires the _full_ [emojibase-data](https://github.com/milesj/emojibase) JSON file, not the "compact" one. If you would like to trim the JSON file down even further, then modify the file to only contain these keys: ```json [ @@ -182,15 +182,15 @@ applyFocusVisiblePolyfill(picker.shadowRoot); ] ``` -You can fetch the emoji JSON file from wherever you want. However, it's recommended that your server expose an `ETag` header. If so, `lite-emoji-picker` can avoid re-downloading the entire JSON file over and over again. Instead, it will fire off a `HEAD` request and just check the `ETag`. +You can fetch the emoji JSON file from wherever you want. However, it's recommended that your server expose an `ETag` header. If so, `emoji-picker-element` can avoid re-downloading the entire JSON file over and over again. Instead, it will fire off a `HEAD` request and just check the `ETag`. If the server hosting the JSON file is not the same as the one containing the emoji picker, then it will also need to expose `Access-Control-Allow-Origin: *` and `Access-Control-Allow-Headers: *`. (Note that `jsdelivr` already does this, which is why it is the default.) -Unfortunately [Safari does not support `Access-Control-Allow-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers#Browser_compatibility), meaning that the `ETag` header will not be available cross-origin. In that case, `lite-emoji-picker` will fall back to the less performant option. +Unfortunately [Safari does not support `Access-Control-Allow-Headers`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers#Browser_compatibility), meaning that the `ETag` header will not be available cross-origin. In that case, `emoji-picker-element` will fall back to the less performant option. ### Offline-first -By default, `lite-emoji-picker` will use the "stale while revalidate" strategy the second time it loads. In other words, it will use any existing data it finds in IndexedDB, and lazily update via the `dataSource` in case data has changed. This means it will work offline-first the second time it runs. +By default, `emoji-picker-element` will use the "stale while revalidate" strategy the second time it loads. In other words, it will use any existing data it finds in IndexedDB, and lazily update via the `dataSource` in case data has changed. This means it will work offline-first the second time it runs. If you would like to manage the database yourself (e.g. to ensure that it's correctly populated before displaying the `Picker`), then create a new `Database` instance and wait for its `ready()` promise to resolve: @@ -203,7 +203,7 @@ try { } ``` -If `lite-emoji-picker` fails to fetch the JSON data the first time it loads, then it will display no emoji. +If `emoji-picker-element` fails to fetch the JSON data the first time it loads, then it will display no emoji. ## Design decisions @@ -218,9 +218,9 @@ Using IndexedDB has a few advantages: ### Native emoji -To avoid downloading a large sprite sheet (which may be copyrighted, or may look out-of-place on different platforms), `lite-emoji-picker` only renders native emoji. This means it is limited to the emoji actually installed on the user's device. +To avoid downloading a large sprite sheet (which may be copyrighted, or may look out-of-place on different platforms), `emoji-picker-element` only renders native emoji. This means it is limited to the emoji actually installed on the user's device. -To avoid rendering ugly unsupported or half-supported emoji, `lite-emoji-picker` will automatically detect emoji support and only render the supported characters. (So no empty boxes or awkward double emoji.) +To avoid rendering ugly unsupported or half-supported emoji, `emoji-picker-element` will automatically detect emoji support and only render the supported characters. (So no empty boxes or awkward double emoji.) ### Browser support diff --git a/package.json b/package.json index 27c15bb..31ec484 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "lite-emoji-picker", + "name": "emoji-picker-element", "version": "1.0.0", "description": "Lightweight emoji picker based on IndexedDB", "main": "index.js", @@ -20,7 +20,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/nolanlawson/lite-emoji-picker.git" + "url": "git+https://github.com/nolanlawson/emoji-picker-element.git" }, "keywords": [ "emoji", @@ -30,9 +30,9 @@ "author": "Nolan Lawson ", "license": "Apache-2.0", "bugs": { - "url": "https://github.com/nolanlawson/lite-emoji-picker/issues" + "url": "https://github.com/nolanlawson/emoji-picker-element/issues" }, - "homepage": "https://github.com/nolanlawson/lite-emoji-picker#readme", + "homepage": "https://github.com/nolanlawson/emoji-picker-element#readme", "devDependencies": { "@babel/preset-env": "^7.10.2", "@peculiar/webcrypto": "^1.1.1", @@ -99,7 +99,7 @@ true, { "ignoreTypes": [ - "lite-emoji-picker" + "emoji-picker" ] } ] diff --git a/src/database/Database.js b/src/database/Database.js index 839755b..99abf72 100644 --- a/src/database/Database.js +++ b/src/database/Database.js @@ -50,7 +50,7 @@ export default class Database { constructor ({ dataSource = DEFAULT_DATA_SOURCE, locale = DEFAULT_LOCALE } = {}) { this._dataSource = dataSource this._locale = locale - this._dbName = `lite-emoji-picker-${this._locale}` + this._dbName = `emoji-picker-element-${this._locale}` this._db = undefined this._ready = this._init() } diff --git a/src/database/utils/warnETag.js b/src/database/utils/warnETag.js index 6949f52..d9c7609 100644 --- a/src/database/utils/warnETag.js +++ b/src/database/utils/warnETag.js @@ -1,5 +1,5 @@ export function warnETag (eTag) { if (!eTag) { - console.warn('lite-emoji-picker is more efficient if the dataSource server exposes an ETag header.') + console.warn('emoji-picker-element is more efficient if the dataSource server exposes an ETag header.') } } diff --git a/src/picker/components/Picker/Picker.html b/src/picker/components/Picker/Picker.html index 70a8ac7..751b850 100644 --- a/src/picker/components/Picker/Picker.html +++ b/src/picker/components/Picker/Picker.html @@ -1,4 +1,4 @@ - +
- Ad-hoc lite-emoji-picker test + Ad-hoc emoji-picker-element test -

Ad-hoc lite-emoji-picker test

+

Ad-hoc emoji-picker-element test

- +