From e8fbde1f61a8894ea83363da27dbecc31da06c0b Mon Sep 17 00:00:00 2001 From: dotCooCoo Date: Tue, 17 Nov 2026 04:10:33 -0800 Subject: [PATCH] ui: add Help search for tools, commands, and tutorials --- crates/ui-egui/src/menus.rs | 3 - crates/ui-egui/src/menus/run.rs | 1 + crates/ui-egui/src/menus/tests.rs | 111 +++++++++++ crates/ui-egui/src/menus/tree.rs | 4 +- crates/ui-egui/src/menus/ui_commands.rs | 19 ++ crates/ui-egui/src/panels.rs | 2 + crates/ui-egui/src/panels/discover.rs | 238 ++++++++++++++++++++++++ crates/ui-egui/src/state.rs | 4 + docs/mcp.md | 25 +++ docs/ui-parity.md | 1 + 10 files changed, 403 insertions(+), 5 deletions(-) create mode 100644 crates/ui-egui/src/panels/discover.rs diff --git a/crates/ui-egui/src/menus.rs b/crates/ui-egui/src/menus.rs index 4e2d80bb45..053eb63d79 100644 --- a/crates/ui-egui/src/menus.rs +++ b/crates/ui-egui/src/menus.rs @@ -37,9 +37,6 @@ fn cp(label: &'static str, id: &'static str, p: Value) -> Item { fn todo(label: &'static str) -> Item { Item::Todo(label, "") } -fn todos(label: &'static str, sc: &'static str) -> Item { - Item::Todo(label, sc) -} fn sub(label: &'static str, items: Vec) -> Item { Item::Sub(label, items) } diff --git a/crates/ui-egui/src/menus/run.rs b/crates/ui-egui/src/menus/run.rs index b4e1c668ac..3b265ad5fe 100644 --- a/crates/ui-egui/src/menus/run.rs +++ b/crates/ui-egui/src/menus/run.rs @@ -115,6 +115,7 @@ pub fn run_ui_command(app: &mut VectorcraftApp, id: &str, p: &Value) -> Option Vec<(&'static str, Vec)> { c("VectorCraft on getartcraft.com", "help.appPage"), c("VectorCraft on GitHub", "help.github"), Sep, - todos("VectorCraft Help…", "F1"), + c("VectorCraft Help…", "help.discover"), c("Safe Mode…", "help.safeMode"), c("Copy Troubleshooting Info", "help.copyTroubleshootingInfo"), Sep, diff --git a/crates/ui-egui/src/menus/ui_commands.rs b/crates/ui-egui/src/menus/ui_commands.rs index 677b804720..d8c44286b0 100644 --- a/crates/ui-egui/src/menus/ui_commands.rs +++ b/crates/ui-egui/src/menus/ui_commands.rs @@ -873,6 +873,25 @@ pub const UI_COMMANDS: &[(&str, &str, &str, &str)] = &[ ("help.about", "About VectorCraft", "", "{}"), ("help.checkForUpdates", "Check for Updates…", "", "{}"), ("help.commandPalette", "Search Commands…", "Cmd+Shift+/", "{}"), + ( + "help.discover", + "VectorCraft Help…", + "F1", + "{query?: string (at most 1024 characters, VectorCraft's limit)} show the Help panel without toggling it closed; a supplied query searches tools, menu commands, and built-in tutorials; omission keeps the current search. Returns {query, results: [{kind: tool|command|tutorial, id, label, path, shortcut}], selected: index|null}", + ), + ( + "help.discover.search", + "Search", + "", + "{query: string (at most 1024 characters, VectorCraft's limit)} search tools, menu commands, and built-in tutorials and show the Help panel; empty or whitespace-only text clears the results. Returns the help.discover result", + ), + ( + "help.discover.choose", + "Select", + "", + "{index: zero-based result index} show a tool's location, a tutorial's steps in Help, or a command's menu path and shortcut without running it; an invalid index is an error. Returns {result: chosen result, location: tool location, tutorial id, or command path}", + ), + ("help.discover.back", "Back", "", "{} return from a Help result to its search results without changing the query"), ( "help.safeMode", "Safe Mode…", diff --git a/crates/ui-egui/src/panels.rs b/crates/ui-egui/src/panels.rs index aa07b13a90..5fb91c3978 100644 --- a/crates/ui-egui/src/panels.rs +++ b/crates/ui-egui/src/panels.rs @@ -17,6 +17,7 @@ pub mod color_guide; pub mod color_themes; pub mod color_wheel; pub mod css_properties; +pub mod discover; pub mod doc_info; pub mod flattener_preview; pub mod glyphs; @@ -188,6 +189,7 @@ pub fn show_icon_panel(app: &mut VectorcraftApp, ui: &mut Ui, id: &str) { three_d::ID => three_d::show(app, ui), script_console::ID => script_console::show(app, ui), learn::ID => learn::show(app, ui), + discover::ID => discover::show(app, ui), crate::addons::cleanup::ID => crate::addons::cleanup::show(app, ui), crate::addons::color::ID => crate::addons::color::show(app, ui), crate::addons::packaging::ID => crate::addons::packaging::show(app, ui), diff --git a/crates/ui-egui/src/panels/discover.rs b/crates/ui-egui/src/panels/discover.rs new file mode 100644 index 0000000000..33df5c2db7 --- /dev/null +++ b/crates/ui-egui/src/panels/discover.rs @@ -0,0 +1,238 @@ +//! Help searches the tools, menu commands, and built-in tutorials. + +use egui::Ui; +use serde::Serialize; +use serde_json::{Value, json}; + +use crate::{VectorcraftApp, menus}; + +pub const ID: &str = "discover"; +const MAX_QUERY: usize = 1024; + +#[derive(Clone, Debug, Serialize)] +pub struct Hit { + pub kind: &'static str, + pub id: String, + pub label: String, + pub path: Vec, + pub shortcut: String, +} + +#[derive(Clone, Debug, Default)] +pub struct View { + pub query: String, + pub results: Vec, + pub selected: Option, + pub focus: bool, +} + +fn matches(query: &str, text: &str) -> bool { + let text = text.to_lowercase(); + query.split_whitespace().all(|word| text.contains(word)) +} + +fn search(app: &VectorcraftApp, query: &str) -> Vec { + let query = query.trim().to_lowercase(); + if query.is_empty() { + return Vec::new(); + } + let mut hits = Vec::new(); + let lang = crate::i18n::current(); + for tool in vectorcraft_tools::catalog::all_tools() { + let label = crate::i18n::tr(lang, tool.label); + if matches(&query, &format!("{} {label} {}", tool.label, tool.id)) { + hits.push(Hit { + kind: "tool", + id: tool.id.into(), + label: label.into(), + path: vec![], + shortcut: crate::shortcut_editor::tool_shortcut(tool.id).unwrap_or_default().into(), + }); + } + } + for entry in menus::menu_entries(app) { + let Some(id) = entry.command else { continue }; + let label = crate::i18n::tr(lang, &entry.label); + let path: Vec = entry.path.iter().map(|part| crate::i18n::tr(lang, part).into()).collect(); + if matches(&query, &format!("{} {label} {} {} {id}", entry.label, entry.path.join(" "), path.join(" "))) { + hits.push(Hit { kind: "command", id, label: label.into(), path, shortcut: entry.shortcut }); + } + } + for skill in super::learn::catalog::SKILLS { + for tutorial in skill.tutorials { + if matches(&query, &format!("{} {} {}", skill.title, tutorial.title, tutorial.id)) { + hits.push(Hit { + kind: "tutorial", + id: tutorial.id.into(), + label: tutorial.title.into(), + path: vec![skill.title.into()], + shortcut: String::new(), + }); + } + } + } + hits +} + +fn results(app: &VectorcraftApp) -> Value { + json!({"query": app.ui.discover.query, "results": app.ui.discover.results, "selected": app.ui.discover.selected}) +} + +fn set_query(app: &mut VectorcraftApp, query: &str) { + app.ui.discover.results = search(app, query); + app.ui.discover.query = query.into(); + app.ui.discover.selected = None; +} + +pub(crate) fn command(app: &mut VectorcraftApp, id: &str, p: &Value) -> Option> { + let spec = menus::UI_COMMANDS.iter().find(|spec| spec.0 == id && id.starts_with("help.discover"))?; + if let Err(e) = vectorcraft_engine::cmd::params::check_keys(id, spec.3, p) { + return Some(Err(e.to_string())); + } + Some(match id { + "help.discover" | "help.discover.search" => { + let query = match p.get("query") { + Some(Value::String(query)) => Some(query.as_str()), + None if id == "help.discover" => None, + _ => { + let key = "query"; + return Some(Err(format!("`{key}` must be a string"))); + } + }; + if let Some(query) = query { + if query.chars().take(MAX_QUERY + 1).count() > MAX_QUERY { + let label = "query"; + let max = MAX_QUERY; + return Some(Err(format!("{label} must be at most {max} characters"))); + } + set_query(app, query); + } + app.ui.discover.focus = true; + crate::panel_docking::reveal_panel(app, ID).map(|_| results(app)) + } + "help.discover.choose" => { + let hit = p + .get("index") + .and_then(Value::as_u64) + .and_then(|i| usize::try_from(i).ok()) + .and_then(|i| app.ui.discover.results.get(i).cloned().map(|hit| (i, hit))); + let Some((index, hit)) = hit else { + return Some(Err("index out of range".into())); + }; + let outcome = match hit.kind { + "tool" => app.run("learn.locateTool", json!({"tool": hit.id})), + "tutorial" => Ok(json!({"tutorial": hit.id})), + _ => Ok(json!({"command": hit.id, "path": hit.path, "shortcut": hit.shortcut})), + }; + outcome.and_then(|outcome| { + crate::panel_docking::reveal_panel(app, ID)?; + app.ui.discover.selected = Some(index); + app.ui.discover.focus = true; + Ok(json!({"result": hit, "location": outcome})) + }) + } + "help.discover.back" => { + app.ui.discover.selected = None; + app.ui.discover.focus = true; + Ok(results(app)) + } + _ => return None, + }) +} + +pub fn show(app: &mut VectorcraftApp, ui: &mut Ui) { + let mut query = app.ui.discover.query.clone(); + let field = ui.add(egui::TextEdit::singleline(&mut query).char_limit(MAX_QUERY).hint_text(tl!("Search")).desired_width(f32::INFINITY)); + if std::mem::take(&mut app.ui.discover.focus) { + field.request_focus(); + } + if field.changed() + && let Err(e) = app.run("help.discover.search", json!({"query": query})) + { + app.status(e); + } + if (field.has_focus() || field.lost_focus()) + && !app.session.tool_busy() + && !app.session.tool_composing() + && ui.input_mut(|i| i.consume_key(egui::Modifiers::NONE, egui::Key::Escape)) + { + if let Err(e) = app.run("window.panel.close", json!({"panel": ID})) { + app.status(e); + } + return; + } + let mut chosen = None; + let mut home = false; + let mut back = false; + let mut locate = None; + ui.horizontal(|ui| { + home = ui.button(tl!("Home")).clicked(); + if app.ui.discover.selected.is_some() { + back = ui.button(tl!("Back")).clicked(); + } + }); + crate::widgets::divider(ui); + if let Some(hit) = app.ui.discover.selected.and_then(|i| app.ui.discover.results.get(i)) { + ui.heading(&hit.label); + if !hit.path.is_empty() { + ui.label(hit.path.join(" › ")); + } + if !hit.shortcut.is_empty() { + ui.label(menus::pretty_shortcut(&hit.shortcut)); + } + if hit.kind == "tutorial" + && let Some((_, tutorial)) = super::learn::catalog::tutorial(&hit.id) + { + for (index, step) in tutorial.steps.iter().enumerate() { + ui.label(format!("{}. {}", index + 1, step.plain())); + if let Some(tool) = step.tool + && let Some(info) = vectorcraft_tools::tool_info(tool) + && ui.link(crate::i18n::tr(crate::i18n::current(), info.label)).clicked() + { + locate = Some(tool); + } + } + } + } else { + egui::ScrollArea::vertical().id_salt("discover-results").show(ui, |ui| { + if app.ui.discover.results.is_empty() && !query.trim().is_empty() { + ui.label(tl!("No results")); + } + for kind in ["tool", "command", "tutorial"] { + let label = match kind { + "tool" => tl!("Tools"), + "command" => tl!("Search Commands…"), + _ => tl!("Learn"), + }; + let mut heading = false; + for (index, hit) in app.ui.discover.results.iter().enumerate().filter(|(_, h)| h.kind == kind) { + if !heading { + crate::widgets::subheader(ui, label); + heading = true; + } + if ui.selectable_label(false, &hit.label).on_hover_text(hit.path.join(" › ")).clicked() { + chosen = Some(index); + } + } + } + }); + } + if home { + if let Err(e) = app.run("help.discover.search", json!({"query": ""})) { + app.status(e); + } + } else if back { + if let Err(e) = app.run("help.discover.back", json!({})) { + app.status(e); + } + } else if let Some(index) = chosen + && let Err(e) = app.run("help.discover.choose", json!({"index": index})) + { + app.status(e); + } + if let Some(tool) = locate + && let Err(e) = app.run("learn.locateTool", json!({"tool": tool})) + { + app.status(e); + } +} diff --git a/crates/ui-egui/src/state.rs b/crates/ui-egui/src/state.rs index ac241a5ebd..ea962600cb 100644 --- a/crates/ui-egui/src/state.rs +++ b/crates/ui-egui/src/state.rs @@ -225,6 +225,7 @@ pub const ICON_PANELS: &[(&str, &str, &str)] = &[ (crate::panels::variables::ID, "Variables", "chart-column"), (crate::panels::script_console::ID, "Script Console", "message-circle"), (crate::panels::learn::ID, "Learn", "graduation-cap"), + (crate::panels::discover::ID, "VectorCraft Help…", "search"), (crate::addons::cleanup::ID, "Artwork Cleanup", "sparkles"), (crate::addons::color::ID, "Color Effects", "sun"), (crate::addons::packaging::ID, "Fold Lines", "scissors"), @@ -421,6 +422,8 @@ pub struct UiState { /// The Learn panel's tab, skill and tutorial, kept while the app runs. #[serde(skip)] pub learn: crate::panels::learn::View, + #[serde(skip)] + pub discover: crate::panels::discover::View, /// The tool whose place a Learn tutorial step's link shows (`learn.locateTool`), while its mark /// is on screen. Not saved. #[serde(skip)] @@ -1154,6 +1157,7 @@ impl Default for UiState { color_settings_scroll: false, find_font_in: String::new(), learn: Default::default(), + discover: Default::default(), learn_locate: None, learn_practice: Default::default(), learn_progress: Default::default(), diff --git a/docs/mcp.md b/docs/mcp.md index a27f99feba..0ab865a7a9 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -3256,6 +3256,31 @@ own layout rules. {"name":"invoke_menu","arguments":{"command":"window.toolbar.dock","params":{"name":"Toolbar 1","side":"left","order":0}}} ``` +## Help search + +Help › VectorCraft Help… and F1 show the Help panel. `help.discover {query?}` opens it without +toggling it closed. A supplied string searches tools, menu commands, and VectorCraft's built-in +tutorials. Omitting `query` preserves the current search. Empty or whitespace-only text clears +the results. VectorCraft limits a query to 1024 characters and rejects a longer supplied string. + +`help.discover.search {query}` runs the same search and shows the panel. Both commands return +`{query, results: [{kind, id, label, path, shortcut}], selected}`. `kind` is `tool`, `command`, or +`tutorial`; `selected` is a zero-based result index or `null`. Search matches all the query's +words without regard to case, using translated tool and command labels as well as their English +labels, ids, and menu paths. Tutorial text remains in English. + +`help.discover.choose {index}` shows that result. A tool result marks its toolbar location without +choosing the tool. A command result shows its menu path and current shortcut without running it. +A tutorial result shows its numbered steps; a tool link in a step marks that tool's location. +The reply is `{result, location}`, with the chosen result and the tool-location reply, tutorial +id, or command path. An invalid index returns an error and preserves the selected result. + +Home clears the search. Back and `help.discover.back {}` return to its results with the query +preserved. Escape in the search field closes the panel. Escape on the canvas still cancels an +active tool operation. The panel uses the existing tool-location marks; command guidance is a +menu path. Articles, Quick Actions, personalized recommendations, and Discover preferences are +not included. + ## Learn panel Window › Learn and the Explore tutorials button beside the search field at the right end of the app bar show and hide diff --git a/docs/ui-parity.md b/docs/ui-parity.md index b312abae1b..5e695beb66 100644 --- a/docs/ui-parity.md +++ b/docs/ui-parity.md @@ -399,6 +399,7 @@ next unit in the order a right-click on a ruler lists them, from Feet back to Po |---|---|---| | Effect > Warp Options: style previews, orientation choices and percent controls | done | #1760; focused input, mixed-style and history checks passed; original captures reviewed. No geometry or optional Properties changes. | | Command search: Up and Down move through the results, Enter runs the highlighted one | done | #1798 (#1757) | +| Help › VectorCraft Help… and F1 show in-app search for tools, menu commands, and built-in tutorials. Tool results mark their toolbar location; command results show their menu path and shortcut without running them; tutorial results show their steps. Home clears the search, Back returns to the results, and Escape in the search field closes the panel. | partial | [Public source](https://helpx.adobe.com/illustrator/desktop/get-started/learn-the-basics/learn-with-discover-panel.html); `help.discover`, `help.discover.search`, `help.discover.choose`, `help.discover.back`; `menus::tests::help_f1_opens_discover_without_a_document`. Articles, Quick Actions, and Discover preferences are not implemented. Menu-path text instead of a menu location marker is VectorCraft's current guidance. | | Learn panel: Window › Learn and Explore tutorials on the app bar open it; For you holds a Quick skill guide card, Skills lists VectorCraft's own skills with progress rings that fill and counts of tutorials finished, a tutorial shows its numbered steps with a check box each that marks the step done once its sample is open, a finished tutorial has a check mark, Back goes up a level; a tool's name in a step is a link that marks the tool where the toolbars show it (its button, its group's flyout, a torn-off strip, a toolbar made with New Toolbar or the All Tools drawer) without choosing it; View more opens the tutorial's practice sample as a new untitled document, Finish tutorial then marks it finished with all its steps, and Next Up shows the next tutorial in the same skill; Reset progress clears the progress (no video) | done | [the help page](https://helpx.adobe.com/illustrator/desktop/get-started/learn-the-basics/learn-skills-quick-skill-guide.html); `learn.list`, `learn.tab`, `learn.skills`, `learn.skill`, `learn.show`, `learn.back`, `learn.locateTool`, `learn.openSample`, `learn.markStep`, `learn.finish`, `learn.next`, `learn.resetProgress`; the mark's look and 3-second lifetime, marking steps by hand, keeping the progress in the preferences and Reset progress are VectorCraft's own rules; `panels::learn::tests`, `toolbar::tests` | | Pathfinder panel: a group selected alone counts its nested shapes, so an expanded stroked object keeps the Shape Modes enabled | done | #1642 (#1635) | | Selected Grid Repeat shows row, column and corner handles and spacing sliders; bounding-box handles take priority where they meet | done | #2691, `tools/src/repeat_grid.rs`; [public behavior reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/set-grid-repeat-options.html); drags preview and commit `object.repeat.options` as one undo step, Escape cancels; a selected Radial Repeat shows an instances handle below it (16 px of drag per instance, 1 to 1,000) and a radius handle on its circle the same way (`tools/src/repeat_radial.rs`; [public behavior reference](https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/create-radial-repeats.html)), and a splitter on its circle that hides the instances it is dragged back past while the others keep their places, and shows them again when dragged forward (its place half a step past the last instance shown and its limit of one instance shown are VectorCraft's own rules) |