|
| 1 | +import { HUB_UI_HIDE_EVENT } from '../constants' |
| 2 | + |
| 3 | +/** |
| 4 | + * How the embedded floating dock reveals itself on a fresh page — the |
| 5 | + * reference UI's port of Nuxt DevTools' opt-in overlay, published as |
| 6 | + * `ConnectionMeta.configs.ui.embeddedVisibility` and set via |
| 7 | + * `createUi({ embeddedVisibility })`. |
| 8 | + * |
| 9 | + * - `normal` (default) — the dock is shown immediately. |
| 10 | + * - `passive` — the dock starts hidden and a console hint offers the reveal |
| 11 | + * shortcut; revealing persists per-origin, so later sessions on this |
| 12 | + * browser start shown. The "Hide" command returns to passive. |
| 13 | + * - `hidden` — the dock starts hidden and the shortcut reveals it for the |
| 14 | + * current session only; nothing is persisted. |
| 15 | + * |
| 16 | + * Whatever the policy, the reveal state is a user-overridable preference — |
| 17 | + * the same shape as the float/edge dock mode: the config seeds it, the |
| 18 | + * visitor's own reveal/hide wins from then on. |
| 19 | + */ |
| 20 | +export type EmbeddedVisibility = 'normal' | 'passive' | 'hidden' |
| 21 | + |
| 22 | +/** Per-origin persisted reveal flag for `passive` mode. */ |
| 23 | +const REVEAL_STORAGE_KEY = 'devframes-dock-revealed' |
| 24 | + |
| 25 | +function readPersistedReveal(): boolean { |
| 26 | + try { |
| 27 | + return localStorage.getItem(REVEAL_STORAGE_KEY) === 'true' |
| 28 | + } |
| 29 | + catch { |
| 30 | + return false |
| 31 | + } |
| 32 | +} |
| 33 | + |
| 34 | +function persistReveal(revealed: boolean): void { |
| 35 | + try { |
| 36 | + if (revealed) |
| 37 | + localStorage.setItem(REVEAL_STORAGE_KEY, 'true') |
| 38 | + else |
| 39 | + localStorage.removeItem(REVEAL_STORAGE_KEY) |
| 40 | + } |
| 41 | + catch { |
| 42 | + // Private-mode / disabled storage: reveal stays session-only, which is a |
| 43 | + // safe degradation — the dock is still reachable via the shortcut. |
| 44 | + } |
| 45 | +} |
| 46 | + |
| 47 | +function isMac(): boolean { |
| 48 | + return typeof navigator !== 'undefined' && /mac/i.test(navigator.userAgent) |
| 49 | +} |
| 50 | + |
| 51 | +/** The reveal shortcut label, `Shift+Alt+D` (`⇧⌥D` on macOS). */ |
| 52 | +function revealShortcutLabel(): string { |
| 53 | + return isMac() ? '⇧⌥D' : 'Shift+Alt+D' |
| 54 | +} |
| 55 | + |
| 56 | +function printHint(label: string): void { |
| 57 | + // Intentional user-facing hint (not a diagnostic) — the whole point of |
| 58 | + // passive mode is this one console line pointing at the reveal shortcut. |
| 59 | + // eslint-disable-next-line no-console |
| 60 | + console.info( |
| 61 | + `%c${label}%c is in passive mode — press %c${revealShortcutLabel()}%c to reveal the devtools.`, |
| 62 | + 'font-weight:bold', |
| 63 | + '', |
| 64 | + 'font-weight:bold', |
| 65 | + '', |
| 66 | + ) |
| 67 | +} |
| 68 | + |
| 69 | +/** `true` when the event is the reveal chord (Shift+Alt+D), layout-agnostic. */ |
| 70 | +function isRevealChord(e: KeyboardEvent): boolean { |
| 71 | + return e.shiftKey && e.altKey && !e.ctrlKey && !e.metaKey && e.code === 'KeyD' |
| 72 | +} |
| 73 | + |
| 74 | +export interface EmbeddedVisibilityHandlers { |
| 75 | + /** Mount/attach the dock element. */ |
| 76 | + show: () => void |
| 77 | + /** Detach the dock element. */ |
| 78 | + hide: () => void |
| 79 | +} |
| 80 | + |
| 81 | +/** |
| 82 | + * Drive the embedded dock's reveal lifecycle for the resolved |
| 83 | + * {@link EmbeddedVisibility} mode: decide whether to show on boot, wire the |
| 84 | + * reveal shortcut and the "Hide" command's {@link HUB_UI_HIDE_EVENT}, and |
| 85 | + * persist the reveal for `passive`. |
| 86 | + * |
| 87 | + * `label` is the resolved product name, used in the passive-mode console hint. |
| 88 | + */ |
| 89 | +export function setupEmbeddedVisibility( |
| 90 | + mode: EmbeddedVisibility, |
| 91 | + label: string, |
| 92 | + handlers: EmbeddedVisibilityHandlers, |
| 93 | +): void { |
| 94 | + let shown = mode === 'normal' || (mode === 'passive' && readPersistedReveal()) |
| 95 | + |
| 96 | + function reveal(): void { |
| 97 | + if (shown) |
| 98 | + return |
| 99 | + shown = true |
| 100 | + if (mode === 'passive') |
| 101 | + persistReveal(true) |
| 102 | + handlers.show() |
| 103 | + } |
| 104 | + |
| 105 | + function conceal(): void { |
| 106 | + if (!shown) |
| 107 | + return |
| 108 | + shown = false |
| 109 | + // `normal`/`hidden` hide for the session only; `passive` remembers it so |
| 110 | + // the next load starts hidden again. |
| 111 | + if (mode === 'passive') |
| 112 | + persistReveal(false) |
| 113 | + handlers.hide() |
| 114 | + } |
| 115 | + |
| 116 | + if (shown) |
| 117 | + handlers.show() |
| 118 | + else if (mode === 'passive') |
| 119 | + printHint(label) |
| 120 | + |
| 121 | + // Shift+Alt+D toggles the dock — the always-available "summon" chord. |
| 122 | + window.addEventListener('keydown', (e) => { |
| 123 | + if (!isRevealChord(e)) |
| 124 | + return |
| 125 | + e.preventDefault() |
| 126 | + if (shown) |
| 127 | + conceal() |
| 128 | + else |
| 129 | + reveal() |
| 130 | + }, { capture: true }) |
| 131 | + |
| 132 | + // The in-dock "Hide" command asks to conceal (reload/shortcut brings it back). |
| 133 | + window.addEventListener(HUB_UI_HIDE_EVENT, conceal) |
| 134 | +} |
0 commit comments