Fix docs, update docs for split packages

.nvmrc

@@ -0,0 +1 @@
+v16.15.0

.vscode/tasks.json

@@ -3,13 +3,22 @@
 	"tasks": [
 		{
 			"type": "npm",
-			"script": "storybook",
+			"script": "start",
 			"problemMatcher": [],
-			"label": "npm: storybook",
-			"detail": "start-storybook -p 6006",
+			"label": "run storybook",
 			"group": {
 				"kind": "build",
-				"isDefault": true
+				"isDefault": false
+			}
+		},
+		{
+			"type": "npm",
+			"script": "start:docs",
+			"problemMatcher": [],
+			"label": "run documentation",
+			"group": {
+				"kind": "build",
+				"isDefault": false
 			}
 		}
 	]

docs/docs/01 - getting-started/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Getting Started"
+}

docs/docs/getting-started/installation.md → docs/docs/01 - getting-started/installation.md

@@ -42,13 +42,16 @@ This will expose a `picmo` object in the global window scope with the following
 - `autoTheme`: CSS class for the `auto` theme
 - `darkTheme`: CSS class for the `dark` theme
 - `lightTheme`: CSS class for the `light` theme
-- [`createDatabase`](../api/functions/create-database)
-- [`createPicker`](../api/functions/create-picker)
-- [`createPopup`](../api/functions/create-popup)
-- [`deleteDatabase`](../api/functions/delete-database)
-- [`deleteRecents`](../api/functions/delete-recents)
-- [`NativeRenderer`](../api/classes/native-renderer)
-- [`Renderer`](../api/classes/renderer)
+- [`createDatabase`](../api/picmo/functions/create-database)
+- [`createPicker`](../api/picmo/functions/create-picker)
+- [`deleteDatabase`](../api/picmo/functions/delete-database)
+- [`deleteRecents`](../api/picmo/functions/delete-recents)
+- [`NativeRenderer`](../api/picmo/classes/native-renderer)
+- [`Renderer`](../api/picmo/classes/renderer)
+
+### Popup picker
+
+- [`createPopup`](../api/popup-picker/functions/create-popup)
 
 ### Twemoji renderer
 
@@ -58,7 +61,7 @@ If you want to use the Twemoji renderer, it is a separate UMD module:
 <script src="https://unpkg.com/picmo@5.0.0-beta.3/umd/picmo.twemoji.js"></script>
 ```
 
-This will expose the [`TwemojiRenderer`](../api/classes/twemoji-renderer) class in the global window scope.
+This will expose the [`TwemojiRenderer`](../api/renderer-twemoji/classes/twemoji-renderer) class in the global window scope.
 
 ## Use ESM from CDN
 

docs/docs/02 - usage/01 - creating-pickers.md

@@ -0,0 +1,86 @@
+# Creating pickers
+
+## Inline picker
+
+An inline picker is rendered directly in the page. It is always visible as long as its parent element is visible. There is no concept of opening or closing an inline picker.
+
+### Create a root element
+
+To create an inline picker, you must first create an element that will contain it:
+
+```html
+<div class="pickerContainer"></div>
+```
+
+### Create the picker
+
+A picker is created by calling the [`createPicker`](../api/picmo/functions/create-picker) function. [`createPicker`](../api/picmo/functions/create-picker) accepts many [options](../api/picmo/types/picker-options) but also has sensible defaults. Here is a simple inline picker:
+
+```javascript
+import { createPicker } from 'picmo';
+
+const container = document.querySelector('.pickerContainer');
+const picker = createPicker({
+  rootElement: container
+});
+```
+
+This will render the picker in the `container` element.
+
+## Popup picker
+
+A popup picker is not displayed until it is triggered by clicking on a popup trigger, usually a button. 
+
+To use a popup picker, you must first install the `@picmo/popup-picker` package. This package contains the [`createPopup`](../api/popup-picker/functions/create-popup) function.
+
+[`createPopup`](../api/popup-picker/functions/create-popup) returns a [`PopupPickerController`](../api/popup-picker/classes/popup-picker-controller) object. This object is used to toggle the popup picker.
+
+[`createPopup`](../api/popup-picker/functions/create-popup) takes two arguments: first, the [`PickerOptions`](../api/picmo/types/picker-options) to configure the picker itself, and the the [`PopupOptions`](../api/popup-picker/types/popup-options) which configure the popup.
+
+<pre>
+  createPicker(
+    pickerOptions: <a href="../api/picmo/types/picker-options">PickerOptions</a>,
+    popupOptions: <a href="../api/popup-picker/types/popup-options">PopupOptions</a>
+  ): <a href="../api/popup-picker/classes/popup-picker-controller">PopupPickerController</a>
+</pre>
+
+## Required elements
+
+A popup picker supports two elements to be defined in the [`PopupOptions`](../api/popup-picker/types/popup-options):
+
+- `triggerElement`: The element that will trigger the popup.
+- `referenceElement`: Another element that the popup will be positioned relative to. This isn't required if using fixed positioning.
+
+:::note
+
+The popup does not add any event listeners to the `referenceElement`. It is used for positioning purposes only. You will still need to add a listener such as a click listener to the `triggerElement` to open the popup.
+
+:::
+
+### Positioning the popup
+
+There are two ways a popup picker can be positioned. A position strategy is specified in the [`position`](../api/popup-picker/types/popup-options#position) option. Its value is either a [fixed position object](#fixed-position) or a [relative position value](#positioning-relative-to-another-element).
+
+#### Fixed position
+
+The picker is positioned relative to the viewport and remains fixed there. A fixed position is an object containing one of the following properties: `top`, `bottom`, `left`, `right`. This will set the [`position: fixed`](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS property.
+
+#### Positioning relative to another element
+
+You can also position the popup picker relative to another element's position. Often times, this will be the trigger element. In this case, two options are needed:
+
+- `referenceElement`: The element that the popup picker will be positioned relative to.
+- `position`: A string value, one of the supported [relative position values](../api/popup-picker/types/position#relative-position).
+
+Here's a simple example of a popup picker:
+
+```javascript
+import { createPopup } from 'picmo';
+
+const trigger = document.querySelector('.emoji-button');
+
+const picker = createPopup({
+  referenceElement: trigger,
+  triggerElement: trigger
+});
+```

docs/docs/usage/emoji-version.md → docs/docs/02 - usage/02 - emoji-version.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Emoji versions
 
 PicMo supports all sets of emojis up to the [Emoji 14.0](http://unicode.org/versions/Unicode14.0.0/) standard. However, not all browsers or operating systems will support this version of the Emoji standard.

docs/docs/usage/renderers.md → docs/docs/02 - usage/03 - renderers.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Renderers
 
 An emoji renderer is a class that, given an emoji sequence, will generate the content to be displayed and emitted. 
@@ -24,7 +20,7 @@ const picker = createPicker({
 
 ## Twemoji
 
-[Twemoji](https://twemoji.twitter.com/) is a free emoji library from Twitter. It contains images for each emoji. The [`TwemojiRenderer`](../api/classes/twemoji-renderer) will render the emojis using the images from Twemoji. By default, these are rendered as SVGs. PNGs can be used instead by passing `png` as the `format` option to the renderer constructor.
+[Twemoji](https://twemoji.twitter.com/) is a free emoji library from Twitter. It contains images for each emoji. The [`TwemojiRenderer`](../api/renderer-twemoji/classes/twemoji-renderer) will render the emojis using the images from Twemoji. By default, these are rendered as SVGs. PNGs can be used instead by passing `png` as the `format` option to the renderer constructor.
 
 ```javascript
 import { TwemojiRenderer } from 'picmo/renderers/twemoji';
@@ -40,9 +36,9 @@ For more information on Twemoji, see [the project page](https://twemoji.twitter.
 
 The built-in renderers (native and Twemoji) both have pros and cons.
 
-- The [`NativeRenderer`](../api/classes/native-renderer) renders quickly because all the emojis are text nodes. However, because new emojis must be added via an operating system update, this may limit the available emojis. Also, the emojis will appear differently depending on the operating system.
+- The [`NativeRenderer`](../api/picmo/classes/native-renderer) renders quickly because all the emojis are text nodes. However, because new emojis must be added via an operating system update, this may limit the available emojis. Also, the emojis will appear differently depending on the operating system.
 
-- The [`TwemojiRenderer`](../api/classes/twemoji-renderer) has a consistent cross-platform look for emojis. It generally will get support for new emojis before operating systems do. However, there is a performance cost because each emoji is an individual image file (Twemoji does not use a sprite sheet).
+- The [`TwemojiRenderer`](../api/renderer-twemoji/classes/twemoji-renderer) has a consistent cross-platform look for emojis. It generally will get support for new emojis before operating systems do. However, there is a performance cost because each emoji is an individual image file (Twemoji does not use a sprite sheet).
 
 ## Creating a custom renderer
 

docs/docs/usage/category-filter.md → docs/docs/02 - usage/04 - category-filter.md

@@ -16,7 +16,7 @@ By default, all categories are shown in the following order:
 
 ## Customizing the categories
 
-The [`PickerOptions`](../api/types/picker-options#categories-categorykey--undefined) supports a `categories` property. This can be used to limit which categories are shown, and in what order. The array should contain [category keys](../api/types/category-key).
+The [`PickerOptions`](../api/picmo/types/picker-options#categories) supports a `categories` property. This can be used to limit which categories are shown, and in what order. The array should contain [category keys](../api/picmo/types/category-key).
 
 If this option is not specified, the categories specified above will be shown. If it _is_ specified, only the categories whose keys are in this array will be shown in the picker. The categories will be shown in the order they appear in the array.
 

docs/docs/usage/custom.md → docs/docs/02 - usage/05 - custom.md

@@ -2,17 +2,17 @@
 
 In addition to emojis defined by the Unicode standard, you can add your own custom images to the picker. This is similar to other pickers, such as the ones in Slack or Discord.
 
-Data about custom images are passed in the optional `custom` array in the [`PickerOptions`](../api/types/picker-options) object.
+Data about custom images are passed in the optional `custom` array in the [`PickerOptions`](../api/picmo/types/picker-options) object.
 
 ## Defining custom images
 
-The `custom` array includes [`CustomEmoji`](../api/types/custom-emoji) objects.
+The `custom` array includes [`CustomEmoji`](../api/picmo/types/custom-emoji) objects.
 
 The value of the `emoji` property for each item must be unique. It serves as a unique key to identify the image.
 
 ### Arbitrary data
 
-A custom image can also have arbitrary data associated with it. This data is stored in the `data` property of the [`CustomEmoji`](../api/types/custom-emoji) object.
+A custom image can also have arbitrary data associated with it. This data is stored in the `data` property of the [`CustomEmoji`](../api/picmo/types/custom-emoji) object. When a custom image is selected, this data is included in the emitted data.
 
 ### Tags
 

docs/docs/usage/emoji-data.md → docs/docs/02 - usage/06 - emoji-data.md

@@ -32,7 +32,7 @@ const picker = createPicker({
 
 Once the data is available, whether provided in the bundle or downloaded from the CDN, it is used to populate an IndexedDB database of the emoji data. Databases are locale-specific - a new database is created per locale used by the picker.
 
-The database is automatically created when the picker is first initialized if it one does not already exist. However, you can also pre-create the database ahead of time by calling [`createDatabase`](../api/functions/create-database).
+The database is automatically created when the picker is first initialized if it one does not already exist. However, you can also pre-create the database ahead of time by calling [`createDatabase`](../api/picmo/functions/create-database).
 
 All picker instances share the same database.
 

docs/docs/usage/emoji-selection.md → docs/docs/02 - usage/07 - emoji-selection.md

@@ -1,6 +1,6 @@
 # Emoji selection
 
-When an emoji is selected in the picker, it will emit an `emoji:select` event with an [`EmojiSelection`](../api/types/emoji-selection) object containing information about the emoji that was selected. 
+When an emoji is selected in the picker, it will emit an `emoji:select` event with an [`EmojiSelection`](../api/picmo/types/emoji-selection) object containing information about the emoji that was selected. 
 
 ## Native emojis
 

docs/docs/usage/i18n.md → docs/docs/02 - usage/08 - i18n.md

@@ -51,4 +51,4 @@ export default {
 };
 ```
 
-To specify a different set of strings, simply create a module that exports these messages and pass it as the [`i18n`](../api/types/picker-options#i18n-dictionary) option.
+To specify a different set of strings, simply create a module that exports these messages and pass it as the [`i18n`](../api/picmo/types/picker-options#i18n) option.

docs/docs/usage/popup-picker.md → docs/docs/02 - usage/10 - popup-picker.md

@@ -6,6 +6,6 @@ A popup picker is closed when one of the following occurs:
 
 - `close` is called on the picker
 - `toggle` is called on the picker when it is open
-- the user clicks anywhere outside of the picker or its trigger element (can be disabled by setting the [`hideOnClickOutside`](../api/types/picker-options#hideonclickoutside-boolean) option to `false`)
-- the user presses the `Escape` key (when the main emoji grid is showing) (can be disabled by setting the [`hideOnEscape`](../api/types/picker-options#hideonescape-boolean) option to `false`)
-- when an emoji is emitted (can be disabled by setting the [`hideOnEmojiSelect`](../api/types/picker-options#hideonemojiselect-boolean) option to `false`)
+- the user clicks anywhere outside of the picker or its trigger element (can be disabled by setting the [`hideOnClickOutside`](../api/popup-picker/types/popup-options#hideonclickoutside) option to `false`)
+- the user presses the `Escape` key (when the main emoji grid is showing) (can be disabled by setting the [`hideOnEscape`](../api/popup-picker/types/popup-options#hideonescape) option to `false`)
+- when an emoji is emitted (can be disabled by setting the [`hideOnEmojiSelect`](../api/popup-picker/types/popup-options#hideonemojiselect) option to `false`)

docs/docs/02 - usage/11 - size-layout.md

@@ -0,0 +1,9 @@
+# Size and layout
+
+## Grid size
+
+The emojis in the picker are laid out in a grid. By default, the visible grid is 8 columns by 6 rows. This can be changed by specifying the [`emojisPerRow`](../api/picmo/types/picker-options#emojisperrow) and [`visibleRows`](../api/picmo/types/picker-options#visiblerows) properties in [`PickerOptions`](../api/picmo/types/picker-options).
+
+## Emoji size
+
+The size of the individual emojis in the grid can also be changed. The default size is `2em`. This can be changed by specifying the [`emojiSize`](../api/picmo/types/picker-options#emojisize) property in [`PickerOptions`](../api/picmo/types/picker-options). This can be any valid CSS size value.

docs/docs/usage/themes.md → docs/docs/02 - usage/12 - themes.md

@@ -8,12 +8,12 @@ PicMo ships with three built-in themes:
 
 ## Specifying a theme
 
-The theme is specified with the `theme` option in the [`PickerOptions`](../api/types/picker-options#theme-string) object.
+The theme is specified with the `theme` option in the [`PickerOptions`](../api/picmo/types/picker-options#theme) object.
 
-The theme names are exported from the `picmo/themes` submodule:
+The theme names are exported directly from the `picmo` module:
 
 ```javascript
-import { autoTheme, lightTheme, darkTheme } from 'picmo/themes';
+import { autoTheme, lightTheme, darkTheme } from 'picmo';
 ```
 ## Custom theming
 

docs/docs/usage/ui-elements.md → docs/docs/02 - usage/13 - ui-elements.md

@@ -9,7 +9,7 @@ A PicMo picker contains several independent UI elements:
 - *Preview*. Used to preview an emoji on focus or hover.
 - *Variant popup*. Used to select a variant of an emoji.
 
-By default, all of these elements are shown. The [`PickerOptions`](../api/types/picker-options) object supports several flags that can be used to disable search, category tabs, recents, preview, and variants:
+By default, all of these elements are shown. The [`PickerOptions`](../api/picmo/types/picker-options) object supports several flags that can be used to disable search, category tabs, recents, preview, and variants:
 
 - `showSearch`
 - `showCategoryTabs`
@@ -18,7 +18,7 @@ By default, all of these elements are shown. The [`PickerOptions`](../api/types/
 - `showVariants`
 
 :::tip
-If you only enable a few categories for the picker, you may want to [adjust the number of rows and columns](size-layout) to make the overall picker smaller, otherwise the picker may not look great:
+If you only enable a few categories for the picker, you may want to [adjust the number of rows and columns](size-layout) to make the overall picker smaller to prevent huge category buttons:
 
 ![few categories with wide picker](@site/static/img/usage/few-categories.png)
 :::

docs/docs/02 - usage/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Using PicMo"
+}

docs/docs/api/picmo/classes/renderer.md

@@ -6,7 +6,7 @@ Controls how emoji are rendered, and also the data that is emitted when an emoji
 
 :::note
 
-You won't need to work with the `Renderer` class unless you are writing a custom renderer. Otherwise, you can just instantiate the [`NativeRenderer`](./native-renderer) or [`TwemojiRenderer`](./twemoji-renderer) classes as needed.
+You won't need to work with the `Renderer` class unless you are writing a custom renderer. Otherwise, you can just instantiate the [`NativeRenderer`](./native-renderer) or [`TwemojiRenderer`](../../renderer-twemoji/classes/twemoji-renderer) classes as needed.
 
 :::
 

docs/docs/api/picmo/types/picker-options.md

@@ -6,8 +6,6 @@ A `PickerOptions` object is passed to the `createPicker` and `createPopup` funct
 
 ## Properties
 
-The following properties are supported for both inline and popup pickers.
-
 ### `animate`
 
 - **Type**: `boolean`