design_shortcuts.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/view/design_ir.hpp>  // AudioWidgetType (detect_audio_widget return)
#include <string>
#include <vector>
 
namespace pulp::view {
 
// ── Keyboard shortcut import (UX best-practice default) ─────────────────
//
// React designs commonly declare keyboard shortcuts inline via
// `onKeyDown={e => { if (e.key === 'Escape') ... }}`,
// `window.addEventListener('keydown', e => { if (e.metaKey && e.key === 's') ... })`,
// or `useHotkeys('cmd+s', ...)`. The design-import path scans the bundled
// React source for these patterns and emits a manifest the runtime can
// register via `registerShortcut(key, modifiers, callback)`. Default-on;
// opt out with `--no-import-shortcuts` (CLI) for designs where the host
// owns shortcut handling.
 
struct DetectedShortcut {
    std::string pattern;

    std::string key;

    std::vector<std::string> modifiers;

    std::string source_location;

    std::string handler_excerpt;
};

std::vector<DetectedShortcut> extract_keyboard_shortcuts(
    const std::string& source, const std::string& filename = "");

std::string serialize_detected_shortcuts(const std::vector<DetectedShortcut>& shortcuts);
 
// ── Default shortcuts (source-matched only) ─────────────────────────────
//
// On top of the explicit-source extractor (which captures shortcuts the
// developer *already wrote*), the default-shortcuts pass adds bindings the
// developer *would expect* per platform convention but didn't write: `Cmd+,` for
// Settings, `Cmd+?` / `F1` for Help, bare `?` for a shortcut cheatsheet,
// `Cmd+S` for Save, etc.
//
// Hard rule: a wrong auto-binding is worse than no binding. The detector
// requires AT LEAST TWO independent signals (component name, canonical name,
// ARIA role/label, modal heading, content shape) before firing, and emits a
// `default_collision` entry instead of a binding when multiple modals look like
// the same pattern.
//
// What this pass does NOT cover: Pulp-framework-provided surfaces (Audio /
// MIDI Settings tabs in standalone). Those need a separate codegen path that
// drives the TabPanel select-tab API and is gated on the build mode.

enum class DefaultShortcutPattern {
    settings,    // Settings / Preferences modal
    help,        // Help / About / Documentation modal (prose-style)
    cheatsheet,  // Shortcut cheatsheet modal (<kbd>-list style)
    new_file,    // "New" button
    open_file,   // "Open" button
    save_file,   // "Save" button
    find,        // Find / Search input
};

struct DefaultShortcutCandidate {
    DefaultShortcutPattern pattern;
    std::string target;
    std::string confidence;
    std::vector<std::string> signals;
};

struct DefaultShortcutCollision {
    DefaultShortcutPattern pattern;
    std::vector<std::string> candidates;  // component names
    std::string reason;
};

struct DefaultShortcutScan {
    std::vector<DefaultShortcutCandidate> accepted;
    std::vector<DefaultShortcutCollision> collisions;
};

DefaultShortcutScan detect_default_shortcuts(
    const std::string& source,
    const std::vector<DetectedShortcut>& existing_extracted);

enum class TargetPlatform { macos, win_linux };
 
std::vector<DetectedShortcut> apply_default_shortcuts(
    const std::vector<DefaultShortcutCandidate>& accepted,
    TargetPlatform platform);

std::string serialize_default_shortcut_scan(const DefaultShortcutScan& scan);
 

bool looks_like_bundler_entry(const std::string& html);

AudioWidgetType detect_audio_widget(const std::string& name);
 
} // namespace pulp::view