From e968d27b50e2bb95b4e30651c6405db7408c57e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Roman=20O=C5=BEana?= <roman@ozana.cz>
Date: Fri, 8 Dec 2023 15:23:09 +0100
Subject: [PATCH] Docs update

---
 .npmignore     |  1 +
 docs/readme.md | 77 ++++++++++++++++++++++++++++++++++++++++++++++----
 readme.md      |  5 +---
 3 files changed, 74 insertions(+), 9 deletions(-)

diff --git a/.npmignore b/.npmignore
index fc0c262..ddb2afa 100644
--- a/.npmignore
+++ b/.npmignore
@@ -1,2 +1,3 @@
 assets
+docs
 examples
\ No newline at end of file
diff --git a/docs/readme.md b/docs/readme.md
index 2d55288..e317128 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -1,4 +1,71 @@
-# Command dialog (cmd-dialog)
+# Command dialog (cmd-dialog) documentation
+
+## `cmd-dialog` element
+
+The `cmd-dialog` element is a custom element that represents the dialog box.
+
+```html
+<cmd-dialog [attributes]></cmd-dialog>
+
+<script type="module">
+	const dialog = document.querySelector('cmd-dialog');
+	dialog.actions = [
+		// ...
+	];
+</script>
+```
+
+### Dialog parameters
+
+- `actions` - List of actions. See [Action](#action) for more information.
+- `isOpen` - Boolean value that indicates whether the dialog is open or not.
+
+```js
+const dialog = document.querySelector('cmd-dialog');
+
+if (dialog.isOpen) {
+  // dialog is open
+}
+```
+
+### HTML Attributes
+
+- `theme` - Theme of the dialog. Possible values: `light` or `dark`. Default value is taken from browser preference.
+- `hotkey` - List of hotkeys. Default value: `$mod+k`.
+- `placeholder` - Placeholder text for the search input. Default value: `Type a command or search...`.
+- `note` - The note in the footer of the dialog box. Default value show number of options.
+
+### Custom events
+
+There is three custom events that are fired by the `cmd-dialog`.
+
+- `open` - fired when the dialog is opened.
+- `close` - fired when the dialog is closed.
+- `action` - fired when the action is selected.
+
+The event `action` is fired when the action is executed. It can be triggered by a keyboard shortcut, an enter key, or a mouse click.
+The `event.detail` has the following properties:
+
+- `search` - The search string from the search input.
+- `action` - The action object.
+- `parentEvent` - The original event that caused the *action*. Can be either `KeyboardEvent` or `CustomEvent`.
+
+Event `action` si cancelable. If you want to prevent perform the action, you can call `event.preventDefault()`.
+
+```js
+// listen to action events
+dialog.addEventListener('action', (event) => {
+
+  // event.detail.parentEvent can be either KeyboardEvent or CustomEvent 
+  if (
+    dialog.isOpen &&
+    event.detail.parentEvent instanceof KeyboardEvent &&
+    event.detail.parentEvent.key !== 'Enter'
+  ) {
+    event.preventDefault(); // do not fire action when dialog is open and key is not Enter
+  }
+});
+```
 
 ## Action
 
@@ -22,7 +89,7 @@ const actions = [
     title: 'Action 1',
     description: 'Description of action 1',
     img: '<svg>...</svg>',
-    hotkey: 'ctrl+a',
+    hotkey: 'Control+a',
     url: 'https://example.com',
     target: '_blank',
     onAction: () => console.log('Action was selected'),
@@ -101,9 +168,9 @@ const actions = [
 ];
 ```
 
-Event object can be weather [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent) or
-`CustomEvent` depending on the action type. The `KeyboardEvent` is passed when the action is
-selected by the keyboard shortcut or by the `Enter` key. The `CustomEvent` is passed when the
+Event object can be either [`KeyboardEvent`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent) or `CustomEvent` depending on the
+action type. The `KeyboardEvent` is passed when the action is selected by the keyboard
+shortcut or by the `Enter` key. The `CustomEvent` is passed when the
 action is selected by the mouse click.
 
 #### Preventing dialog from closing
diff --git a/readme.md b/readme.md
index 1495d04..c302d15 100644
--- a/readme.md
+++ b/readme.md
@@ -43,10 +43,7 @@ or inside module script
 
 ### Attributes
 
-- `theme` - Theme of the dialog. Possible values: `light` or `dark`. Default value is taken from browser preference.
-- `hotkey` - List of hotkeys. Default value: `ctrl+k,cmd+k`.
-- `placeholder` - Placeholder text for the search input. Default value: `Type a command or search...`.
-- `note` - The note in the footer of the dialog box. Default value show number of options.
+
 
 ## Dependencies