rename to emoji-picker-element
This commit is contained in:
Nolan Lawson
parent
79db2b2847
commit
1eb0c4c115
54
README.md
54
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
|
||||
<lite-emoji-picker></lite-emoji-picker>
|
||||
<emoji-picker></emoji-picker>
|
||||
```
|
||||
|
||||
```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
|
||||
<lite-emoji-picker class="dark"></lite-emoji-picker>
|
||||
<lite-emoji-picker class="light"></lite-emoji-picker>
|
||||
<emoji-picker class="dark"></emoji-picker>
|
||||
<emoji-picker class="light"></emoji-picker>
|
||||
```
|
||||
|
||||
###### 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
|
||||
|
||||
|
|
|
|||
10
package.json
10
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 <nolan@nolanlawson.com>",
|
||||
"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"
|
||||
]
|
||||
}
|
||||
]
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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.')
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
<svelte:options tag="lite-emoji-picker" />
|
||||
<svelte:options tag="emoji-picker" />
|
||||
<section
|
||||
class="picker"
|
||||
aria-label={i18n.regionLabel}
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title>Ad-hoc lite-emoji-picker test</title>
|
||||
<title>Ad-hoc emoji-picker-element test</title>
|
||||
<style>
|
||||
.container {
|
||||
height: 300px;
|
||||
|
|
@ -11,9 +11,9 @@
|
|||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Ad-hoc lite-emoji-picker test</h1>
|
||||
<h1>Ad-hoc emoji-picker-element test</h1>
|
||||
<div class="container">
|
||||
<lite-emoji-picker></lite-emoji-picker>
|
||||
<emoji-picker></emoji-picker>
|
||||
</div>
|
||||
<script type="module">
|
||||
import './index.js'
|
||||
|
|
|
|||
Loading…
Reference in New Issue