diff --git a/crates/engine/src/cmd/create.rs b/crates/engine/src/cmd/create.rs index 0ce38be40b..e248f2bbc3 100644 --- a/crates/engine/src/cmd/create.rs +++ b/crates/engine/src/cmd/create.rs @@ -55,7 +55,7 @@ pub fn specs() -> Vec { "Flare", [], None, - "{cx, cy, diameter=100, opacity=50 (%), brightness=30 (%), growth=20 (%), fuzziness=50 (%), rays=15, longest=300 (%), rayFuzziness=100 (%), rotation=0 (deg, turns the rays clockwise), x2?, y2? (ring end; else pathLength at direction), pathLength=300, rings=10, largest=50 (%), direction=45 (deg counter-clockwise from 3 o'clock: where the rings run from the centre), seed?, ringSeed? (whole number below 2^53: deterministically places every ring along the path, including the first for small seed values, keeping their count and sizes)} → {id}", + "{cx, cy, diameter=100, opacity=50 (%), brightness=30 (%), growth=20 (%), fuzziness=50 (%), rays=15, longest=300 (%), rayFuzziness=100 (%), rotation=0 (deg, turns the rays clockwise), x2?, y2? (ring end, both or neither: one alone is an error; else pathLength at direction), pathLength=300, rings=10, largest=50 (%), direction=45 (deg counter-clockwise from 3 o'clock: where the rings run from the centre), seed?, ringSeed? (whole number below 2^53: deterministically places every ring along the path, including the first for small seed values, keeping their count and sizes)} → {id}", has_doc, super::flare::flare ), diff --git a/crates/engine/src/cmd/flare.rs b/crates/engine/src/cmd/flare.rs index 8871ddf921..17a566e29c 100644 --- a/crates/engine/src/cmd/flare.rs +++ b/crates/engine/src/cmd/flare.rs @@ -65,12 +65,14 @@ fn settings_of(p: &Value, cmd: &str) -> Result { }; let rays = count_or(p, "rays", 15, cmd)?.min(50); let rings = count_or(p, "rings", 10, cmd)?.min(50); + // The end point is given whole or not at all: a lone `x2` or `y2` is refused. let end = match (p.get("x2").and_then(Value::as_f64), p.get("y2").and_then(Value::as_f64)) { (Some(x), Some(y)) => Point::new(x, y), - _ => { + (None, None) => { let a = f64_or(p, "direction", 45.0).to_radians(); finite_end(c + Vec2::new(a.cos(), -a.sin()) * f64_or(p, "pathLength", 300.0), cmd)? } + _ => Point::new(f64_req(p, "x2", cmd)?, f64_req(p, "y2", cmd)?), }; let mut v = json!({ "cx": c.x, "cy": c.y, "x2": end.x, "y2": end.y, "rays": rays, "rings": rings, "seed": seed }); if let Some(r) = ring_seed { diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index c39c88cbbb..3d5cd0f82d 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -3491,6 +3491,65 @@ fn flare_counts_are_whole_numbers() { assert!(s.execute("shape.flare", &json!({"cx": 100, "cy": 100, "rays": 2.5})).is_err()); } +/// `shape.flare` given only one of `x2` and `y2`, the other left out or null, refuses the call +/// naming the missing one, draws nothing and adds no undo step. +#[test] +fn flare_requires_both_endpoint_coordinates() { + let mut s = session(); + let state = |s: &Session| { + let st = s.doc().unwrap(); + (st.doc.node_count(), st.history.undo.len(), st.history.redo.len()) + }; + let before = state(&s); + for (p, key) in [ + (json!({"cx": 100, "cy": 100, "x2": 300}), "y2"), + (json!({"cx": 100, "cy": 100, "x2": 300, "y2": null}), "y2"), + (json!({"cx": 100, "cy": 100, "y2": 300}), "x2"), + (json!({"cx": 100, "cy": 100, "x2": null, "y2": 300}), "x2"), + ] { + let err = s.execute("shape.flare", &p).expect_err(&p.to_string()).to_string(); + assert_eq!(err, format!("invalid parameters for `shape.flare`: missing number `{key}`"), "{p}"); + assert_eq!(state(&s), before, "{p}"); + } +} + +/// `shape.flare` with neither `x2` nor `y2` (left out or null) places the rings' end point from +/// `pathLength` and `direction`; with both it uses them. +#[test] +fn flare_omitted_or_null_endpoint_coordinates_use_path_fallback() { + let mut s = session(); + let mut end = |p: serde_json::Value| { + let id = NodeId(s.execute("shape.flare", &p).unwrap()["id"].as_u64().unwrap()); + let spec = flare_settings(&s.doc().unwrap().doc, id).expect("a flare"); + Point::new(spec.params["x2"].as_f64().unwrap(), spec.params["y2"].as_f64().unwrap()) + }; + for p in [ + json!({"cx": 100, "cy": 100, "pathLength": 200, "direction": 0}), + json!({"cx": 100, "cy": 100, "pathLength": 200, "direction": 0, "x2": null}), + json!({"cx": 100, "cy": 100, "pathLength": 200, "direction": 0, "y2": null}), + json!({"cx": 100, "cy": 100, "pathLength": 200, "direction": 0, "x2": null, "y2": null}), + ] { + let e = end(p.clone()); + assert!((e.x - 300.0).abs() < 1e-9 && (e.y - 100.0).abs() < 1e-9, "{p}: {e:?}"); + } + assert_eq!(end(json!({"cx": 100, "cy": 100, "pathLength": 200, "direction": 0, "x2": 40, "y2": 70})), Point::new(40.0, 70.0)); +} + +/// Settings a file holds with only one of `x2` and `y2` are not a flare's: the group stays as art, +/// but is not a flare that can be edited. +#[test] +fn flare_settings_with_a_lone_endpoint_coordinate_are_not_a_flare() { + let mut s = session(); + let id = NodeId(s.execute("shape.flare", &json!({"cx": 100, "cy": 100, "rings": 2})).unwrap()["id"].as_u64().unwrap()); + let mut d = (*s.doc().unwrap().doc).clone(); + assert!(flare_settings(&d, id).is_some()); + let mut extras = d.node_mut(id).unwrap().extras_mut(); + let spec = extras.flare.as_deref_mut().expect("flare settings"); + spec.params.as_object_mut().unwrap().remove("y2"); + drop(extras); + assert!(flare_settings(&d, id).is_none()); +} + /// `shape.editFlare` on a flare scaled far down: a `pathLength`, an end point or a center that, /// taken back to where the flare was drawn, is not a finite number is an error, and the flare keeps /// its settings. diff --git a/docs/mcp.md b/docs/mcp.md index e7abf476a9..8a876ec69c 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -2412,6 +2412,9 @@ and `amount` in `color.harmony`; `angle` in `paint.editGradient` and in the `gra `paint.freeform.splitLine`; `tolerance` and `gap` in `shapeBuilder.merge`; `gap` in `shapeBuilder.regions` and `shapeBuilder.copyRegion`; and `width` and `tolerance` in `livePaint.strokeEdge`. A null is read as a key left out. A gradient stop that names a swatch refuses a `tint` that is not a number with `` stop 0: `tint` must be a number ``. +`shape.flare` takes the rings' end point as both `x2` and `y2` or neither: given only one of them, with the other left +out or null, it answers `` missing number `y2` `` (or `` missing number `x2` ``), draws nothing and adds no undo step. +With neither, `pathLength` and `direction` place the end point. The Edit, document, guide and slice commands also check the type of each param and change nothing when one is wrong. A value that is not a number gets `` `dx` must be a number, not "10" ``: `dx` and `dy` in `edit.duplicate`, diff --git a/docs/target-app-parity.md b/docs/target-app-parity.md index 57ac87a396..9a8f155f43 100644 --- a/docs/target-app-parity.md +++ b/docs/target-app-parity.md @@ -1307,6 +1307,7 @@ Moved from the ROADMAP's "Shipped so far" on 2026-10-10. Update it when a featur - An Alt-click (Option-click on macOS) with the Flare tool draws a flare centered at the click at once, without opening the Flare Tool Options, as [the help page](https://help.adobe.com/archive/en_US/illustrator/cs3/illustrator_cs3_help.pdf) describes for a default flare. As VectorCraft's own rules, the flare takes the tool's current options (the defaults until they are changed), Alt counts when it is held as the button goes down, a drag with Alt still draws the flare in two stages, and on the active perspective plane the flare is the one the click dialog's OK draws there (`alt_click_draws_a_flare_with_the_options_at_once`, `alt_click_draws_on_the_active_perspective_plane`, `an_alt_click_with_the_flare_tool_draws_the_flare_the_click_dialog_draws`). - While a flare's center is dragged out, Ctrl (Command on macOS) keeps the center's size and the drag sizes the halo; while its rings' end point is placed, Up/Down Arrow add and remove rings and ~ places them anew (`shape.flare`'s `ringSeed`) ([Draw and edit flares](https://helpx.adobe.com/illustrator/desktop/draw-shapes-and-paths/draw-shapes/draw-and-edit-flares.html); `flare_arrows_change_the_rays_then_the_rings`, `flare_tilde_places_the_rings_anew`, `flare_ctrl_keeps_the_center_and_the_drag_sizes_the_halo`). - Flare ring placement accepts small `ringSeed` values, including 0, without concentrating the first ring at the center; the same seed and parameters reproduce the same positions. This seed mapping is VectorCraft's own (`flare_small_ring_seeds_spread_the_first_ring_along_the_path`, `flare_ring_seed_moves_only_the_rings`). + - `shape.flare` takes the rings' end point as `x2` and `y2` together: one given alone is an error that draws nothing and adds no undo step, and with neither, `pathLength` and `direction` place it. Saved flare settings that hold only one of them are not read as an editable flare. These are VectorCraft's own rules (`flare_requires_both_endpoint_coordinates`, `flare_omitted_or_null_endpoint_coordinates_use_path_fallback`, `flare_settings_with_a_lone_endpoint_coordinate_are_not_a_flare`). - A plain step of a number field (Up/Down or a wheel notch) goes to the next whole unit in its direction and a Ctrl/Cmd step goes to the next tenth, so 5.1 mm steps up to 6 mm and down to 5 mm (#2881). A Shift step adds or takes ten and keeps the fraction. - In the number, text and color fields of the panels and the Control bar, Shift+Enter (Shift+Return) applies the value and keeps the field active with its value selected; a text box of several lines takes it as a line break. In a dialog, Shift+Enter applies the value and confirms the dialog, as Enter does. - The Pattern Options panel's Name field and the name fields that a double-click opens in the Layers, Artboards and Asset Export panels take Shift+Enter (Shift+Return) the same way: it applies the name and keeps the field active with the name selected.