From f5032dfb87c97be6eca523f15a17202df81d37f8 Mon Sep 17 00:00:00 2001
From: Minsu Lee <amond@amond.net>
Date: Fri, 29 May 2026 00:08:48 +0900
Subject: [PATCH 1/2] feat(layer): add 'd' shortcut to toggle color mode

Press 'd' to toggle between light and dark color modes. The shortcut
is configurable via app.config.ts (docs.shortcuts.toggleColorMode) and
can be disabled by setting it to an empty string.

The handler bails out when:
- the color mode is forced (colorMode.forced === true)
- the keystroke originated from an editable element (<input>, <textarea>,
  <select>, [contenteditable])
- any modifier key (meta / ctrl / alt / shift) is pressed

Reimplemented from upstream docus commit 61c36d03 (feat(layer): add d
shortcut to toggle color mode (#1377)) using @vueuse/core's onKeyStroke
instead of @nuxt/ui's defineShortcuts, since this project does not
depend on @nuxt/ui.

Refs: docs/docus-upstream-changes.md item #11
---
 packages/layer/app/app.config.ts              |  3 +
 .../layer/app/composables/useDocsShortcuts.ts | 63 +++++++++++++++++++
 .../layer/app/plugins/shortcuts.client.ts     |  9 +++
 packages/layer/modules/config.ts              |  3 +
 packages/layer/nuxt.schema.ts                 | 14 +++++
 5 files changed, 92 insertions(+)
 create mode 100644 packages/layer/app/composables/useDocsShortcuts.ts
 create mode 100644 packages/layer/app/plugins/shortcuts.client.ts

diff --git a/packages/layer/app/app.config.ts b/packages/layer/app/app.config.ts
index 51af4d66..f74375af 100644
--- a/packages/layer/app/app.config.ts
+++ b/packages/layer/app/app.config.ts
@@ -17,5 +17,8 @@ export default defineAppConfig({
       url: '',
       branch: 'main',
     },
+    shortcuts: {
+      toggleColorMode: 'd',
+    },
   },
 })
diff --git a/packages/layer/app/composables/useDocsShortcuts.ts b/packages/layer/app/composables/useDocsShortcuts.ts
new file mode 100644
index 00000000..72ca55cf
--- /dev/null
+++ b/packages/layer/app/composables/useDocsShortcuts.ts
@@ -0,0 +1,63 @@
+import { onKeyStroke } from '@vueuse/core'
+
+/**
+ * Returns `true` when the keystroke originated from an editable element
+ * (`<input>`, `<textarea>`, or any element with `[contenteditable]`),
+ * in which case the shortcut should be ignored so the user can type freely.
+ */
+function isEditableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement))
+    return false
+
+  const tag = target.tagName
+  if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
+    return true
+
+  if (target.isContentEditable)
+    return true
+
+  return false
+}
+
+/**
+ * Registers a keyboard shortcut (default `d`) that toggles between
+ * light and dark color modes. Mirrors docus' `useDocusShortcuts`
+ * composable (upstream commit `61c36d03`) but is reimplemented on top of
+ * `@vueuse/core`'s `onKeyStroke` instead of `@nuxt/ui`'s `defineShortcuts`.
+ *
+ * The handler bails out when:
+ * - the color mode is forced (e.g. `colorMode.forced === true`),
+ * - the keystroke originated from an editable element,
+ * - any modifier key (meta / ctrl / alt / shift) is pressed,
+ * - the configured shortcut is empty.
+ */
+export function useDocsShortcuts(): void {
+  const appConfig = useAppConfig()
+  const colorMode = useColorMode()
+
+  const toggleColorModeShortcut = computed<string>(
+    () => appConfig.docs?.shortcuts?.toggleColorMode ?? 'd',
+  )
+
+  onKeyStroke(
+    (event: KeyboardEvent) => {
+      const key = toggleColorModeShortcut.value
+      if (!key)
+        return false
+      return event.key?.toLowerCase() === key.toLowerCase()
+    },
+    (event: KeyboardEvent) => {
+      if (colorMode.forced)
+        return
+
+      if (event.metaKey || event.ctrlKey || event.altKey || event.shiftKey)
+        return
+
+      if (isEditableTarget(event.target))
+        return
+
+      const resolved = colorMode.value === 'dark' ? 'light' : 'dark'
+      colorMode.preference = resolved
+    },
+  )
+}
diff --git a/packages/layer/app/plugins/shortcuts.client.ts b/packages/layer/app/plugins/shortcuts.client.ts
new file mode 100644
index 00000000..ed7be778
--- /dev/null
+++ b/packages/layer/app/plugins/shortcuts.client.ts
@@ -0,0 +1,9 @@
+/**
+ * Installs the documentation layer's keyboard shortcuts on app boot.
+ *
+ * Client-only because the shortcut targets `window` keystrokes, which
+ * have no meaning on the server.
+ */
+export default defineNuxtPlugin(() => {
+  useDocsShortcuts()
+})
diff --git a/packages/layer/modules/config.ts b/packages/layer/modules/config.ts
index b63431aa..996b12ee 100644
--- a/packages/layer/modules/config.ts
+++ b/packages/layer/modules/config.ts
@@ -24,6 +24,9 @@ export default defineNuxtModule({
         url: gitInfo?.url,
         branch: getGitBranch(),
       },
+      shortcuts: {
+        toggleColorMode: 'd',
+      },
     })
 
     // SEO defaults
diff --git a/packages/layer/nuxt.schema.ts b/packages/layer/nuxt.schema.ts
index c8b19dec..5bccd10e 100644
--- a/packages/layer/nuxt.schema.ts
+++ b/packages/layer/nuxt.schema.ts
@@ -107,6 +107,20 @@ export default defineNuxtSchema({
           },
         },
       },
+      shortcuts: {
+        $schema: {
+          title: 'Keyboard Shortcuts',
+          description: 'Keyboard shortcuts configuration',
+        },
+        toggleColorMode: {
+          $default: 'd',
+          $schema: {
+            title: 'Toggle Color Mode',
+            description: 'Shortcut to toggle light and dark mode. Leave empty to disable.',
+            type: 'string',
+          },
+        },
+      },
     },
   },
 })

From e8b70d2806255e5ea07676b2fcbeb8b5369d7ef2 Mon Sep 17 00:00:00 2001
From: Minsu Lee <amond@amond.net>
Date: Fri, 29 May 2026 00:45:45 +0900
Subject: [PATCH 2/2] fix(layer): apply review suggestions for color mode
 shortcut

Applies feedback from gemini-code-assist review:
- Explicitly import `computed` from vue for IDE/test environments
- Traverse up the DOM in `isEditableTarget` so non-HTMLElement targets
  (SVGElement, MathMLElement) inside contenteditable containers are
  still treated as editable and do not trigger the shortcut
---
 .../layer/app/composables/useDocsShortcuts.ts    | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/layer/app/composables/useDocsShortcuts.ts b/packages/layer/app/composables/useDocsShortcuts.ts
index 72ca55cf..6296c2df 100644
--- a/packages/layer/app/composables/useDocsShortcuts.ts
+++ b/packages/layer/app/composables/useDocsShortcuts.ts
@@ -1,19 +1,29 @@
 import { onKeyStroke } from '@vueuse/core'
+import { computed } from 'vue'
 
 /**
  * Returns `true` when the keystroke originated from an editable element
  * (`<input>`, `<textarea>`, or any element with `[contenteditable]`),
  * in which case the shortcut should be ignored so the user can type freely.
+ *
+ * Traverses up the DOM tree from the event target so that non-`HTMLElement`
+ * descendants (e.g. `SVGElement`, `MathMLElement`) inside an editable
+ * container are still treated as editable.
  */
 function isEditableTarget(target: EventTarget | null): boolean {
-  if (!(target instanceof HTMLElement))
+  let el: Node | null = target instanceof Node ? target : null
+  while (el && !(el instanceof HTMLElement)) {
+    el = el.parentNode
+  }
+
+  if (!el)
     return false
 
-  const tag = target.tagName
+  const tag = el.tagName
   if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT')
     return true
 
-  if (target.isContentEditable)
+  if (el.isContentEditable)
     return true
 
   return false