From 22fdb3f36a3b65f46b546a3c5bfa5cb5b286444c Mon Sep 17 00:00:00 2001
From: Cem Aksoylar <caksoylar@users.noreply.github.com>
Date: Tue, 13 Aug 2024 10:31:22 -0700
Subject: [PATCH] feat(docs): Add keyboard vs consumer variants note

---
 docs/docs/codes/applications.mdx              |  2 ++
 docs/docs/codes/editing.mdx                   |  2 ++
 docs/docs/codes/index.mdx                     |  2 ++
 docs/docs/codes/media.mdx                     |  2 ++
 docs/docs/codes/power.mdx                     |  2 ++
 .../src/components/codes/KeyboardConsumer.jsx | 30 +++++++++++++++++++
 6 files changed, 40 insertions(+)
 create mode 100644 docs/src/components/codes/KeyboardConsumer.jsx

diff --git a/docs/docs/codes/applications.mdx b/docs/docs/codes/applications.mdx
index 68e24d36..538e50a4 100644
--- a/docs/docs/codes/applications.mdx
+++ b/docs/docs/codes/applications.mdx
@@ -6,10 +6,12 @@ hide_title: true
 
 import OsLegend from "@site/src/components/codes/OsLegend";
 import ToastyContainer from "@site/src/components/codes/ToastyContainer";
+import KeyboardConsumer from "@site/src/components/codes/KeyboardConsumer";
 import Content, { toc as contentToc } from "./_applications.mdx";
 
 export const toc = contentToc;
 
+<KeyboardConsumer />
 <OsLegend />
 <ToastyContainer />
 <Content />
diff --git a/docs/docs/codes/editing.mdx b/docs/docs/codes/editing.mdx
index 3475d6c2..7caadacc 100644
--- a/docs/docs/codes/editing.mdx
+++ b/docs/docs/codes/editing.mdx
@@ -7,9 +7,11 @@ hide_title: true
 import OsLegend from "@site/src/components/codes/OsLegend";
 import ToastyContainer from "@site/src/components/codes/ToastyContainer";
 import Content, { toc as contentToc } from "./_editing.mdx";
+import KeyboardConsumer from "@site/src/components/codes/KeyboardConsumer";
 
 export const toc = contentToc;
 
+<KeyboardConsumer />
 <OsLegend />
 <ToastyContainer />
 <Content />
diff --git a/docs/docs/codes/index.mdx b/docs/docs/codes/index.mdx
index a701b4ce..892bd497 100644
--- a/docs/docs/codes/index.mdx
+++ b/docs/docs/codes/index.mdx
@@ -6,6 +6,7 @@ slug: ./
 ---
 
 import SpellingCaution from "@site/src/components/codes/SpellingCaution";
+import KeyboardConsumer from "@site/src/components/codes/KeyboardConsumer";
 import OsLegend from "@site/src/components/codes/OsLegend";
 import ToastyContainer from "@site/src/components/codes/ToastyContainer";
 import Key, { toc as keyToc } from "./_keyboard-keypad.mdx";
@@ -25,6 +26,7 @@ export const toc = [
 ];
 
 <SpellingCaution />
+<KeyboardConsumer />
 <OsLegend />
 <ToastyContainer />
 <Key />
diff --git a/docs/docs/codes/media.mdx b/docs/docs/codes/media.mdx
index c7884479..b0e5c2c0 100644
--- a/docs/docs/codes/media.mdx
+++ b/docs/docs/codes/media.mdx
@@ -7,9 +7,11 @@ hide_title: true
 import OsLegend from "@site/src/components/codes/OsLegend";
 import ToastyContainer from "@site/src/components/codes/ToastyContainer";
 import Content, { toc as contentToc } from "./_media.mdx";
+import KeyboardConsumer from "@site/src/components/codes/KeyboardConsumer";
 
 export const toc = contentToc;
 
+<KeyboardConsumer />
 <OsLegend />
 <ToastyContainer />
 <Content />
diff --git a/docs/docs/codes/power.mdx b/docs/docs/codes/power.mdx
index 2af3233f..af8405ab 100644
--- a/docs/docs/codes/power.mdx
+++ b/docs/docs/codes/power.mdx
@@ -7,9 +7,11 @@ hide_title: true
 import OsLegend from "@site/src/components/codes/OsLegend";
 import ToastyContainer from "@site/src/components/codes/ToastyContainer";
 import Content, { toc as contentToc } from "./_power.mdx";
+import KeyboardConsumer from "@site/src/components/codes/KeyboardConsumer";
 
 export const toc = contentToc;
 
+<KeyboardConsumer />
 <OsLegend />
 <ToastyContainer />
 <Content />
diff --git a/docs/src/components/codes/KeyboardConsumer.jsx b/docs/src/components/codes/KeyboardConsumer.jsx
new file mode 100644
index 00000000..94f64146
--- /dev/null
+++ b/docs/src/components/codes/KeyboardConsumer.jsx
@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) 2024 The ZMK Contributors
+ *
+ * SPDX-License-Identifier: CC-BY-NC-SA-4.0
+ */
+
+import Admonition from "@theme/Admonition";
+
+export default function KeyboardConsumer() {
+  return (
+    <Admonition type="info" title="Keyboard vs. Consumer keycodes">
+      <p>
+        In the below tables, there are keycode pairs with similar names where
+        one variant has a <code>K_</code> prefix and another <code>C_</code>.
+        These variants correspond to similarly named usages from different{" "}
+        <a href="https://usb.org/sites/default/files/hut1_2.pdf#page=16">
+          HID usage pages
+        </a>
+        , namely the "keyboard/keypad" and "consumer" ones respectively.
+      </p>
+      <p>
+        In practice, some OS and applications might listen to only one of the
+        variants. You can use the values in the compatibility columns below to
+        assist you in selecting which one to use.
+      </p>
+    </Admonition>
+  );
+}
+
+KeyboardConsumer.propTypes = {};