@wildo-ai/saas-frontend-lib 1.0.1

package/dist/esm/core/guidance/useGuidance.js

@@ -0,0 +1,46 @@
+/**
+ * Guidance Hooks
+ *
+ * Separated from GuidanceContext.tsx for React Fast Refresh compatibility.
+ */
+import { useContext, useMemo } from 'react';
+import { GuidanceContext, GUIDANCE_FALLBACK, LIFECYCLE_DEFAULTS, PROGRESSION_DEFAULTS } from './GuidanceContext.js';
+/**
+ * Hook to access the Guidance context.
+ * Returns safe no-op defaults when called outside provider (safe for SSR/tests).
+ */
+export function useGuidance() {
+    const ctx = useContext(GuidanceContext);
+    return ctx ?? GUIDANCE_FALLBACK;
+}
+/**
+ * Hook to access the Lifecycle slice from GuidanceContext.
+ *
+ * NOTE: The hook-level useMemo here provides marginal benefit on its own because
+ * useContext already triggers a re-render on any context value change. The real
+ * isolation comes from the provider-level useMemo on `lifecycleSlice` (inside
+ * GuidanceContextProvider), which ensures the `lifecycle` reference only changes
+ * when lifecycle data actually changes. This hook-level useMemo acts as a safety
+ * net so callers receive a stable reference even if the context value object is
+ * recreated without lifecycle changes.
+ *
+ * Returns safe no-op defaults when called outside provider.
+ */
+export function useLifecycle() {
+    const ctx = useContext(GuidanceContext);
+    return useMemo(() => ctx?.lifecycle ?? LIFECYCLE_DEFAULTS, [ctx?.lifecycle]);
+}
+/**
+ * Hook to access the Progression slice from GuidanceContext.
+ *
+ * NOTE: Same isolation pattern as useLifecycle — the provider-level useMemo on
+ * `progressionSlice` is what prevents unnecessary re-renders. This hook-level
+ * useMemo is a safety net for reference stability.
+ *
+ * Returns safe no-op defaults when called outside provider.
+ */
+export function useProgression() {
+    const ctx = useContext(GuidanceContext);
+    return useMemo(() => ctx?.progression ?? PROGRESSION_DEFAULTS, [ctx?.progression]);
+}
+//# sourceMappingURL=useGuidance.js.map

package/dist/esm/core/guidance/useGuidance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGuidance.js","sourceRoot":"","sources":["../../../../src/core/guidance/useGuidance.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAuF,iBAAiB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEtM;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,GAAG,IAAI,iBAAiB,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,SAAS,IAAI,kBAAkB,EAAE,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;AAC/E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,GAAG,GAAG,UAAU,CAAC,eAAe,CAAC,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,WAAW,IAAI,oBAAoB,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC;AACrF,CAAC"}

package/dist/esm/core/hotkey/DefaultHotkeyHandler.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Registers config-driven application hotkeys:
+ * - `[HOTKEY].emitShortcuts` → dispatch `FrontendEvents` (sidebar toggle, palette-adjacent surfaces, etc.)
+ * - `[HOTKEY].bindings` → navigate via `resolveHotkeyBindings` / `NavigationUtils`
+ *
+ * Command menu keyboard open is owned by `useCommandMenuBehavior` (`[COMMAND_MENU].openShortcut`),
+ * not this component, so Cmd+K is not double-registered.
+ */
+/**
+ * Renderless component — registers hotkeys from `[HOTKEY]` config.
+ */
+export declare function DefaultHotkeyHandler(): null;
+//# sourceMappingURL=DefaultHotkeyHandler.d.ts.map

package/dist/esm/core/hotkey/DefaultHotkeyHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultHotkeyHandler.d.ts","sourceRoot":"","sources":["../../../../src/core/hotkey/DefaultHotkeyHandler.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiDH;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAsG3C"}

package/dist/esm/core/hotkey/DefaultHotkeyHandler.js

@@ -0,0 +1,120 @@
+/**
+ * Registers config-driven application hotkeys:
+ * - `[HOTKEY].emitShortcuts` → dispatch `FrontendEvents` (sidebar toggle, palette-adjacent surfaces, etc.)
+ * - `[HOTKEY].bindings` → navigate via `resolveHotkeyBindings` / `NavigationUtils`
+ *
+ * Command menu keyboard open is owned by `useCommandMenuBehavior` (`[COMMAND_MENU].openShortcut`),
+ * not this component, so Cmd+K is not double-registered.
+ */
+import { useEffect, useMemo } from 'react';
+import { ApplicationLevelComponentType, HotkeyDispatchableEvent, HotkeyGroup, HotkeyScope, } from '../../core/config/app-level-components.frontend.schemas.js';
+import { useHotkeyRegistry } from './useHotkey.js';
+import { mergeHotkeyEmitShortcuts } from './merge-hotkey-emit-shortcuts.js';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { FrontendEvents, } from '../../core/events/events.frontend.schemas.js';
+import { filterHotkeyBindingsByRuntimeAvailability, useLauncherRuntimeAvailabilityContext, } from '../../core/navigation/launcher-runtime-availability.js';
+import { resolveHotkeyBindings } from '../../core/navigation/launcher-resolution.js';
+import { useLauncherResolutionContext } from '../../core/navigation/useLauncherResolutionContext.js';
+import { useNavigationController } from '../../core/navigation/useNavigationController.js';
+import { NavigationUtils } from '../../core/navigation/navigation.utils.js';
+import { useUI } from '../../core/ui/useUI.js';
+const DEFAULT_EMIT_DESCRIPTION_KEYS = {
+    [HotkeyDispatchableEvent.HOTKEY_SIDEBAR_TOGGLE]: 'engine.hotkeys.sidebarToggle',
+    [HotkeyDispatchableEvent.HOTKEY_NOTIFICATIONS_OPEN]: 'engine.hotkeys.notificationsOpen',
+    [HotkeyDispatchableEvent.HOTKEY_QUICK_SWITCHER_OPEN]: 'engine.hotkeys.quickSwitcherOpen',
+    [HotkeyDispatchableEvent.HOTKEY_SHORTCUTS_HELP]: 'engine.hotkeys.shortcutsHelp',
+};
+function launcherForEmitEvent(event) {
+    switch (event) {
+        case HotkeyDispatchableEvent.HOTKEY_QUICK_SWITCHER_OPEN:
+            return ApplicationLevelComponentType.QUICK_SWITCHER;
+        case HotkeyDispatchableEvent.HOTKEY_NOTIFICATIONS_OPEN:
+            return ApplicationLevelComponentType.NOTIFICATION_CENTER;
+        default:
+            return undefined;
+    }
+}
+/**
+ * Renderless component — registers hotkeys from `[HOTKEY]` config.
+ */
+export function DefaultHotkeyHandler() {
+    const { register } = useHotkeyRegistry();
+    const { emit } = useEventBus();
+    const resolutionCtx = useLauncherResolutionContext();
+    const { navigate } = useNavigationController();
+    const { appComponentsConfiguration } = useUI();
+    const runtimeAvailabilityContext = useLauncherRuntimeAvailabilityContext();
+    const hotkeyConfig = appComponentsConfiguration?.[ApplicationLevelComponentType.HOTKEY];
+    const rawConfigBindings = typeof hotkeyConfig === 'object' && hotkeyConfig !== null
+        ? hotkeyConfig.bindings
+        : undefined;
+    const configBindings = useMemo(() => (filterHotkeyBindingsByRuntimeAvailability(rawConfigBindings, runtimeAvailabilityContext)), [rawConfigBindings, runtimeAvailabilityContext]);
+    const configEmitShortcuts = typeof hotkeyConfig === 'object' && hotkeyConfig !== null
+        ? hotkeyConfig.emitShortcuts
+        : undefined;
+    const emitShortcuts = useMemo(() => mergeHotkeyEmitShortcuts([], configEmitShortcuts), [configEmitShortcuts]);
+    const resolvedBindings = useMemo(() => {
+        if (!configBindings || !resolutionCtx)
+            return [];
+        return resolveHotkeyBindings(configBindings, resolutionCtx);
+    }, [configBindings, resolutionCtx]);
+    useEffect(() => {
+        const unregisterFns = [];
+        const describeEmitRow = (row) => {
+            const key = row.descriptionLabellingRef ?? DEFAULT_EMIT_DESCRIPTION_KEYS[row.event];
+            return resolutionCtx ? resolutionCtx.t(key) : key;
+        };
+        for (const row of emitShortcuts) {
+            if (row.enabled === false)
+                continue;
+            unregisterFns.push(register({
+                id: `app-emit-${row.event}`,
+                shortcut: row.shortcut,
+                description: describeEmitRow(row),
+                scope: row.scope ?? HotkeyScope.GLOBAL,
+                group: row.group,
+                handler: () => {
+                    switch (row.event) {
+                        case HotkeyDispatchableEvent.HOTKEY_SIDEBAR_TOGGLE:
+                            emit(FrontendEvents.HOTKEY_SIDEBAR_TOGGLE, {});
+                            break;
+                        case HotkeyDispatchableEvent.HOTKEY_NOTIFICATIONS_OPEN:
+                            emit(FrontendEvents.HOTKEY_NOTIFICATIONS_OPEN, {});
+                            break;
+                        case HotkeyDispatchableEvent.HOTKEY_QUICK_SWITCHER_OPEN:
+                            emit(FrontendEvents.HOTKEY_QUICK_SWITCHER_OPEN, {});
+                            break;
+                        case HotkeyDispatchableEvent.HOTKEY_SHORTCUTS_HELP:
+                            emit(FrontendEvents.HOTKEY_SHORTCUTS_HELP, {});
+                            break;
+                        default:
+                            break;
+                    }
+                },
+                launcher: launcherForEmitEvent(row.event),
+                preventDefault: row.preventDefault !== false,
+            }));
+        }
+        for (const binding of resolvedBindings) {
+            unregisterFns.push(register({
+                id: `app-hotkey-${binding.id}`,
+                shortcut: binding.shortcut,
+                description: binding.description ?? binding.label,
+                scope: binding.scope ?? HotkeyScope.GLOBAL,
+                group: HotkeyGroup.ACTIONS,
+                handler: () => {
+                    NavigationUtils.dispatchNavigationForResolvedTarget(navigate, binding, ApplicationLevelComponentType.HOTKEY);
+                },
+                launcher: ApplicationLevelComponentType.HOTKEY,
+                preventDefault: true,
+            }));
+        }
+        return () => {
+            for (const unregister of unregisterFns) {
+                unregister();
+            }
+        };
+    }, [register, emit, resolvedBindings, navigate, emitShortcuts, resolutionCtx]);
+    return null;
+}
+//# sourceMappingURL=DefaultHotkeyHandler.js.map

package/dist/esm/core/hotkey/DefaultHotkeyHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultHotkeyHandler.js","sourceRoot":"","sources":["../../../../src/core/hotkey/DefaultHotkeyHandler.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/hotkey/HotkeyRegistryContext.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hotkey Registry Context
+ *
+ * Provides centralized keyboard shortcut management.
+ * Based on Specs §7 - HOTKEY Specification (Infrastructure)
+ */
+import React from 'react';
+import { HotkeyScope } from '../../core/config/app-level-components.frontend.schemas.js';
+import { HotkeyRegistryContextType } from './hotkey-registry.frontend.schemas.js';
+declare const HotkeyRegistryContext: React.Context<HotkeyRegistryContextType>;
+export interface HotkeyRegistryProviderProps {
+    children: React.ReactNode;
+    /** Initial active scope */
+    initialScope?: HotkeyScope;
+}
+export declare const HotkeyRegistryProvider: React.FC<HotkeyRegistryProviderProps>;
+export { HotkeyRegistryContext };
+//# sourceMappingURL=HotkeyRegistryContext.d.ts.map

package/dist/esm/core/hotkey/HotkeyRegistryContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotkeyRegistryContext.d.ts","sourceRoot":"","sources":["../../../../src/core/hotkey/HotkeyRegistryContext.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAA2E,MAAM,OAAO,CAAC;AAChG,OAAO,EAAE,WAAW,EAAE,MAAM,uEAAuE,CAAC;AACpG,OAAO,EAEL,yBAAyB,EAK1B,MAAM,oCAAoC,CAAC;AAE5C,QAAA,MAAM,qBAAqB,0CAAwD,CAAC;AAMpF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,2BAA2B;IAC3B,YAAY,CAAC,EAAE,WAAW,CAAC;CAC5B;AAED,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,EAAE,CAAC,2BAA2B,CAiNxE,CAAC;AAEF,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/esm/core/hotkey/HotkeyRegistryContext.js

@@ -0,0 +1,181 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Hotkey Registry Context
+ *
+ * Provides centralized keyboard shortcut management.
+ * Based on Specs §7 - HOTKEY Specification (Infrastructure)
+ */
+import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { HotkeyScope } from '../../core/config/app-level-components.frontend.schemas.js';
+import { parseShortcut, matchesShortcut, } from './hotkey-registry.frontend.schemas.js';
+const HotkeyRegistryContext = createContext(null);
+function scopesOverlap(a, b) {
+    return a === b || a === HotkeyScope.GLOBAL || b === HotkeyScope.GLOBAL;
+}
+export const HotkeyRegistryProvider = ({ children, initialScope = HotkeyScope.GLOBAL, }) => {
+    // ===================================================================
+    // State
+    // ===================================================================
+    const [activeScope, setActiveScope] = useState(initialScope);
+    const [isPaused, setIsPaused] = useState(false);
+    // Use ref for hotkeys to avoid re-renders on registration
+    const hotkeysRef = useRef(new Map());
+    const [hotkeyVersion, setHotkeyVersion] = useState(0);
+    // ===================================================================
+    // Registration Functions
+    // ===================================================================
+    const register = useCallback((definition) => {
+        const parsed = parseShortcut(definition.shortcut);
+        const conflictingHotkeys = Array.from(hotkeysRef.current.values()).filter((hotkey) => hotkey.id !== definition.id &&
+            hotkey.shortcut.toLowerCase() === definition.shortcut.toLowerCase() &&
+            scopesOverlap(hotkey.scope, definition.scope));
+        if (conflictingHotkeys.length > 0) {
+            console.warn(`[HotkeyRegistry] Duplicate shortcut "${definition.shortcut}" detected. ` +
+                `Resolution is registration-order-dependent; first registered match wins.`, {
+                incomingId: definition.id,
+                existingIds: conflictingHotkeys.map((hotkey) => hotkey.id),
+            });
+        }
+        const registered = {
+            ...definition,
+            enabled: definition.enabled !== false,
+            /** Defaults to true — application hotkeys should prevent browser defaults (e.g. Cmd+K). */
+            preventDefault: definition.preventDefault ?? true,
+            stopPropagation: definition.stopPropagation ?? false,
+            parsed,
+        };
+        hotkeysRef.current.set(definition.id, registered);
+        setHotkeyVersion(v => v + 1);
+        // Return unregister function
+        return () => {
+            hotkeysRef.current.delete(definition.id);
+            setHotkeyVersion(v => v + 1);
+        };
+    }, []);
+    const unregister = useCallback((id) => {
+        hotkeysRef.current.delete(id);
+        setHotkeyVersion(v => v + 1);
+    }, []);
+    const setEnabled = useCallback((id, enabled) => {
+        const hotkey = hotkeysRef.current.get(id);
+        if (hotkey) {
+            hotkey.enabled = enabled;
+            setHotkeyVersion(v => v + 1);
+        }
+    }, []);
+    // ===================================================================
+    // Scope and Pause Functions
+    // ===================================================================
+    const pause = useCallback(() => setIsPaused(true), []);
+    const resume = useCallback(() => setIsPaused(false), []);
+    // ===================================================================
+    // Query Functions
+    // ===================================================================
+    const getHotkeys = useCallback(() => {
+        return Array.from(hotkeysRef.current.values());
+    }, []);
+    const getHotkeysByGroup = useCallback((group) => {
+        return Array.from(hotkeysRef.current.values()).filter((h) => h.group === group);
+    }, []);
+    const getConflicts = useCallback(() => {
+        const byShortcut = new Map();
+        for (const hotkey of hotkeysRef.current.values()) {
+            const key = hotkey.shortcut.toLowerCase();
+            const existing = byShortcut.get(key) ?? [];
+            existing.push(hotkey);
+            byShortcut.set(key, existing);
+        }
+        const conflicts = [];
+        for (const [shortcut, hotkeys] of byShortcut.entries()) {
+            const conflictingIds = hotkeys.filter((candidate) => hotkeys.some((other) => other.id !== candidate.id && scopesOverlap(other.scope, candidate.scope))).map((hotkey) => hotkey.id);
+            if (conflictingIds.length > 1) {
+                conflicts.push({ shortcut, hotkeyIds: conflictingIds });
+            }
+        }
+        return conflicts;
+    }, []);
+    // ===================================================================
+    // Keyboard Event Handler
+    // ===================================================================
+    useEffect(() => {
+        const handleKeyDown = (event) => {
+            // Skip if paused
+            if (isPaused)
+                return;
+            // Skip if target is an input element (unless it's a global shortcut)
+            const target = event.target;
+            let isInputElement = target.tagName === 'INPUT' ||
+                target.tagName === 'TEXTAREA' ||
+                target.isContentEditable;
+            if (isInputElement && target.closest('[data-hotkey-passthrough]')) {
+                isInputElement = false;
+            }
+            // Find matching hotkeys
+            for (const hotkey of hotkeysRef.current.values()) {
+                // Skip disabled hotkeys
+                if (!hotkey.enabled)
+                    continue;
+                // Check scope
+                if (hotkey.scope === HotkeyScope.PAGE && activeScope !== HotkeyScope.PAGE)
+                    continue;
+                if (hotkey.scope === HotkeyScope.COMPONENT && activeScope !== HotkeyScope.COMPONENT)
+                    continue;
+                // Skip non-global hotkeys when in input
+                if (isInputElement && hotkey.scope !== HotkeyScope.GLOBAL)
+                    continue;
+                // Check if shortcut matches
+                if (matchesShortcut(event, hotkey.parsed)) {
+                    // Execute handler
+                    try {
+                        hotkey.handler();
+                    }
+                    catch (error) {
+                        console.error(`Hotkey handler error for ${hotkey.id}:`, error);
+                    }
+                    // Prevent default if configured
+                    if (hotkey.preventDefault) {
+                        event.preventDefault();
+                    }
+                    // Stop propagation if configured
+                    if (hotkey.stopPropagation) {
+                        event.stopPropagation();
+                    }
+                    // Only trigger one hotkey per keystroke
+                    break;
+                }
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [activeScope, isPaused]);
+    // ===================================================================
+    // Context Value
+    // ===================================================================
+    const contextValue = useMemo(() => ({
+        register,
+        unregister,
+        setEnabled,
+        setActiveScope,
+        pause,
+        resume,
+        getHotkeys,
+        getHotkeysByGroup,
+        getConflicts,
+        activeScope,
+        isPaused,
+    }), [
+        register,
+        unregister,
+        setEnabled,
+        pause,
+        resume,
+        getHotkeys,
+        getHotkeysByGroup,
+        getConflicts,
+        activeScope,
+        isPaused,
+    ]);
+    return (_jsx(HotkeyRegistryContext.Provider, { value: contextValue, children: children }));
+};
+export { HotkeyRegistryContext };
+//# sourceMappingURL=HotkeyRegistryContext.js.map

package/dist/esm/core/hotkey/HotkeyRegistryContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotkeyRegistryContext.js","sourceRoot":"","sources":["../../../../src/core/hotkey/HotkeyRegistryContext.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/hotkey/HotkeyShortcutsHelpDialog.d.ts

@@ -0,0 +1,3 @@
+import type { JSX } from 'react';
+export declare function HotkeyShortcutsHelpDialog(): JSX.Element;
+//# sourceMappingURL=HotkeyShortcutsHelpDialog.d.ts.map

package/dist/esm/core/hotkey/HotkeyShortcutsHelpDialog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotkeyShortcutsHelpDialog.d.ts","sourceRoot":"","sources":["../../../../src/core/hotkey/HotkeyShortcutsHelpDialog.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AA0DjC,wBAAgB,yBAAyB,IAAI,GAAG,CAAC,OAAO,CAoHvD"}

package/dist/esm/core/hotkey/HotkeyShortcutsHelpDialog.js

@@ -0,0 +1,91 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useState } from 'react';
+import { FrontendComponentType } from '@wildo-ai/presets-components-models';
+import { HotkeyGroup, HotkeyScope, } from '../../core/config/app-level-components.frontend.schemas.js';
+import { FrontendEvents } from '../../core/events/events.frontend.schemas.js';
+import { useEventBus } from '../../core/events/useEventBus.js';
+import { useHotkeyRegistry } from '../../core/hotkey/useHotkey.js';
+import { useI18n } from '../../core/i18n/useI18n.js';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from '../../components/overlays/containers/dialog.js';
+import { ScrollArea } from '../../components/layout/scroll-area.js';
+const HOTKEY_GROUP_ORDER = [
+    HotkeyGroup.NAVIGATION,
+    HotkeyGroup.ACTIONS,
+    HotkeyGroup.HELP,
+    'other',
+];
+function groupLabel(group, tc) {
+    switch (group) {
+        case HotkeyGroup.NAVIGATION:
+            return tc('navigation');
+        case HotkeyGroup.ACTIONS:
+            return tc('actions');
+        case HotkeyGroup.HELP:
+            return tc('help');
+        default:
+            return tc('other');
+    }
+}
+function scopeLabel(scope, tc) {
+    switch (scope) {
+        case HotkeyScope.GLOBAL:
+            return tc('shortcutsHelpScopeGlobal');
+        case HotkeyScope.PAGE:
+            return tc('shortcutsHelpScopePage');
+        case HotkeyScope.COMPONENT:
+            return tc('shortcutsHelpScopeComponent');
+        default:
+            return tc('shortcutsHelpScopeUnknown');
+    }
+}
+export function HotkeyShortcutsHelpDialog() {
+    const [isOpen, setIsOpen] = useState(false);
+    const { on } = useEventBus();
+    const { getHotkeys, getConflicts, activeScope, isPaused } = useHotkeyRegistry();
+    const { t, tComponent } = useI18n({
+        component: FrontendComponentType.APPLICATION_LEVEL_COMMAND_MENU,
+    });
+    useEffect(() => {
+        return on(FrontendEvents.HOTKEY_SHORTCUTS_HELP, () => {
+            setIsOpen(prev => !prev);
+        });
+    }, [on]);
+    const tc = (key, params) => tComponent(FrontendComponentType.APPLICATION_LEVEL_COMMAND_MENU, key, params);
+    const hotkeys = useMemo(() => {
+        if (!isOpen)
+            return [];
+        return getHotkeys()
+            .slice()
+            .sort((a, b) => {
+            const groupA = HOTKEY_GROUP_ORDER.indexOf(a.group ?? 'other');
+            const groupB = HOTKEY_GROUP_ORDER.indexOf(b.group ?? 'other');
+            if (groupA !== groupB)
+                return groupA - groupB;
+            return a.description.localeCompare(b.description);
+        });
+    }, [getHotkeys, isOpen]);
+    const groupedHotkeys = useMemo(() => {
+        const groups = new Map();
+        for (const hotkey of hotkeys) {
+            const group = hotkey.group ?? 'other';
+            const existing = groups.get(group) ?? [];
+            existing.push(hotkey);
+            groups.set(group, existing);
+        }
+        return HOTKEY_GROUP_ORDER
+            .map(group => ({
+            group,
+            label: groupLabel(group, tc),
+            hotkeys: groups.get(group) ?? [],
+        }))
+            .filter(entry => entry.hotkeys.length > 0);
+    }, [hotkeys, tc]);
+    const conflicts = useMemo(() => {
+        if (!isOpen)
+            return [];
+        return getConflicts();
+    }, [getConflicts, isOpen]);
+    const title = t('engine.hotkeys.shortcutsHelp');
+    return (_jsx(Dialog, { open: isOpen, onOpenChange: setIsOpen, children: _jsxs(DialogContent, { className: "max-w-3xl pt-10", children: [_jsx(DialogHeader, { children: _jsx(DialogTitle, { children: title }) }), _jsxs("div", { className: "space-y-card-sm", children: [_jsxs("div", { className: "flex flex-wrap items-center gap-item-sm text-xs text-muted-foreground", children: [_jsxs("span", { children: [tc('shortcutsHelpActiveScope'), ": ", scopeLabel(activeScope, tc)] }), _jsxs("span", { children: [tc('shortcutsHelpRegistry'), ": ", isPaused ? tc('shortcutsHelpRegistryPaused') : tc('shortcutsHelpRegistryListening')] }), _jsx("span", { children: tc('shortcutsHelpCount', { count: hotkeys.length }) })] }), conflicts.length > 0 && (_jsxs("div", { className: "rounded-md border border-warning/40 bg-warning/10 p-card-sm text-sm text-warning-foreground", children: [_jsx("div", { className: "font-medium", children: tc('shortcutsHelpConflictsDetected') }), _jsx("ul", { className: "mt-item-xs space-y-item-xs", children: conflicts.map(conflict => (_jsxs("li", { children: [_jsx("code", { children: conflict.shortcut }), " ", tc('shortcutsHelpConflictUsedBy'), " ", conflict.hotkeyIds.join(', ')] }, conflict.shortcut))) })] })), _jsx(ScrollArea, { className: "max-h-[60vh] pe-item-sm", children: _jsx("div", { className: "space-y-card", children: groupedHotkeys.map(({ group, label, hotkeys: groupHotkeys }) => (_jsxs("section", { className: "space-y-item-sm", children: [_jsx("h3", { className: "text-sm font-semibold text-foreground", children: label }), _jsx("div", { className: "space-y-item-xs", children: groupHotkeys.map(hotkey => (_jsxs("div", { className: "flex items-start justify-between gap-field rounded-md border border-border/70 px-card-sm py-item-sm", children: [_jsxs("div", { className: "min-w-0 space-y-[2px]", children: [_jsx("div", { className: "text-sm font-medium text-foreground", children: hotkey.description }), _jsxs("div", { className: "flex flex-wrap items-center gap-item-sm text-xs text-muted-foreground", children: [_jsx("span", { children: scopeLabel(hotkey.scope, tc) }), hotkey.launcher && _jsx("span", { children: hotkey.launcher }), _jsx("span", { children: hotkey.id })] })] }), _jsx("kbd", { className: "shrink-0 rounded border border-border bg-muted px-item-sm py-[2px] text-xs font-medium text-foreground", children: hotkey.parsed.display })] }, hotkey.id))) })] }, group))) }) })] })] }) }));
+}
+//# sourceMappingURL=HotkeyShortcutsHelpDialog.js.map

package/dist/esm/core/hotkey/HotkeyShortcutsHelpDialog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HotkeyShortcutsHelpDialog.js","sourceRoot":"","sources":["../../../../src/core/hotkey/HotkeyShortcutsHelpDialog.tsx"],"names":[],"mappings":"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"}

package/dist/esm/core/hotkey/default-hotkeys.frontend.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Optional callback-based hotkey registration (`useDefaultHotkeys`).
+ *
+ * Declarative framework shortcuts belong in app config `[HOTKEY].systemShortcuts`
+ * (defaults: `@wildo-ai/presets-components` → `DEFAULT_HOTKEY_SYSTEM_SHORTCUTS`) and
+ * are wired by `DefaultHotkeyHandler`.
+ */
+/**
+ * Default hotkey definitions for the application
+ */
+export interface DefaultHotkeyHandlers {
+    /** Handler to open the command menu (Cmd+K) */
+    openCommandMenu?: () => void;
+    /** Handler to toggle sidebar (Cmd+B) */
+    toggleSidebar?: () => void;
+    /** Handler to go to home (Cmd+H) */
+    goHome?: () => void;
+    /** Handler to show keyboard shortcuts help (Cmd+/) */
+    showShortcutsHelp?: () => void;
+    /** Handler to focus search (Cmd+F or /) */
+    focusSearch?: () => void;
+    /** Handler to open quick switcher (Cmd+P) */
+    openQuickSwitcher?: () => void;
+    /** Handler to open notifications (Cmd+N) */
+    openNotifications?: () => void;
+    /** Handler to open settings (Cmd+,) */
+    openSettings?: () => void;
+    /** Handler to navigate back (Cmd+[) */
+    navigateBack?: () => void;
+    /** Handler to navigate forward (Cmd+]) */
+    navigateForward?: () => void;
+}
+/**
+ * Hook to register default application hotkeys
+ *
+ * Call this hook in your main application component to set up
+ * default keyboard shortcuts.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const [isCommandMenuOpen, setIsCommandMenuOpen] = useState(false);
+ *
+ *   useDefaultHotkeys({
+ *     openCommandMenu: () => setIsCommandMenuOpen(true),
+ *     toggleSidebar: () => toggleSidebarCollapse(),
+ *   });
+ *
+ *   return <AppLayout />;
+ * }
+ * ```
+ */
+export declare function useDefaultHotkeys(handlers: DefaultHotkeyHandlers): void;
+/**
+ * Get platform-specific modifier key display
+ */
+export declare function getPlatformModifier(): string;
+//# sourceMappingURL=default-hotkeys.frontend.d.ts.map

package/dist/esm/core/hotkey/default-hotkeys.frontend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-hotkeys.frontend.d.ts","sourceRoot":"","sources":["../../../../src/core/hotkey/default-hotkeys.frontend.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;IAC7B,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,oCAAoC;IACpC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,sDAAsD;IACtD,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,4CAA4C;IAC5C,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,0CAA0C;IAC1C,eAAe,CAAC,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,qBAAqB,QAoJhE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C"}