diff --git a/docs/reference/draftwright-report-v8.schema.json b/docs/reference/draftwright-report-v8.schema.json index 0a9ded0e..85f2506d 100644 --- a/docs/reference/draftwright-report-v8.schema.json +++ b/docs/reference/draftwright-report-v8.schema.json @@ -184,8 +184,7 @@ "control": { "const": "side" }, "authored_value": { "enum": ["above", "below", "left", "right"] }, "resolved_value": { "enum": ["above", "below", "left", "right"] } - }, - "not": { "required": ["parameter_id"] } + } }, { "required": ["parameter_id"], diff --git a/docs/reference/reports.md b/docs/reference/reports.md index 16fc9541..a72bdfb1 100644 --- a/docs/reference/reports.md +++ b/docs/reference/reports.md @@ -48,8 +48,8 @@ When a generated or hand-authored sheet uses `sheet.layout_override(...)`, `status: "applied"`, and `intent_class: "layout-only"`. The corresponding feature still carries its complete semantic content and the ordinary shared placement solve still owns coordinates and feasibility. The -side form records a corridor; the dimension form additionally records the exact `parameter_id` -and one-based feature-relative `lane`. The field is emitted as an empty array when no override +side form records a corridor; a dimension-targeted side or lane additionally records the exact +`parameter_id`, and a lane records its one-based feature-relative rank. The field is emitted as an empty array when no override exists; it is optional in the version-8 schema so previously written version-8 documents remain valid. diff --git a/docs/reference/sheet.md b/docs/reference/sheet.md index 5ad04b45..58b03b8a 100644 --- a/docs/reference/sheet.md +++ b/docs/reference/sheet.md @@ -320,10 +320,20 @@ if lane_check["supported"]: sheet.layout_override( "declaration:9", parameter="slot_width.length", lane=3 ) + +# A declared hole diameter can choose a supported callout corridor too. +side_check = sheet.validate_layout_override( + "declaration:hole", parameter="bore.diameter", side="left" +) +if side_check["supported"]: + sheet.layout_override( + "declaration:hole", parameter="bore.diameter", side="left" + ) ``` Without `parameter=`, `layout_options()` reports the declaration's current side and supported -values. With an exact declared parameter it reports dimension-lane capability. A lane is an +values. With an exact declared parameter it reports only the side and/or lane controls that +the dimension renderer actually consumes. A lane is an integer from 1 through 8: a one-based drafting-spaced rank from that dimension's physical witness, not a distance. The shared measured-candidate solve may resolve it into proven whitespace inside or outside the view and records that candidate's region explicitly. The @@ -331,7 +341,9 @@ current lane-capable slice is the linear width/length dimensions of slots. Capab declared in one compiler-owned registry so another dimension family is added deliberately, not by teaching each renderer a private spelling. -The side surface accepts `above`, `below`, `left`, and `right`; +Dimension-side overrides currently cover native hole/pattern callouts and envelope height; +unsupported renderers are not advertised as movable. The side surface accepts `above`, +`below`, `left`, and `right` where the selected renderer supports them; `validate_layout_override()` returns structured `invalid_declaration`, `unsupported_declaration`, `unsupported_control`, or `unsupported_value` refusals, plus `invalid_control_combination` when side and lane addressing @@ -340,14 +352,15 @@ are mixed, without mutating the sheet. Both documents say not that the final sheet has enough space. `build()` and `lint()` remain the authority for feasibility and collision-free placement. -`layout_override()` accepts either keyword-only `side`, or an exact `parameter` plus `lane`, and -rejects duplicate overrides for the same target. Side chooses a feature corridor; lane ranks a +`layout_override()` accepts keyword-only `side` for a feature corridor, or an exact `parameter` +with `side` or `lane` for a declared dimension, and rejects duplicate overrides for the same +target. Side chooses a supported corridor; lane ranks a parallel position for one referential dimension. Neither is pinning or priority, and neither moves an annotation to a caller-supplied coordinate or changes its measurement, tolerance, datum, or other engineering semantics. Generated scripts emit the override as a separate line after the identity-bearing declarations. A declared report records the requested and resolved value under `layout.overrides` with -`intent_class: "layout-only"`; lane rows also retain `parameter_id`. An infeasible lane drops +`intent_class: "layout-only"`; dimension-targeted rows also retain `parameter_id`. An infeasible lane drops honestly with the requested lane in the lint message. Omitting the override retains the existing placement behaviour. diff --git a/src/draftwright/model/ir.py b/src/draftwright/model/ir.py index fd838663..aaddf10d 100644 --- a/src/draftwright/model/ir.py +++ b/src/draftwright/model/ir.py @@ -2717,8 +2717,8 @@ def __post_init__(self) -> None: class LayoutOverride: """One append-only layout-only edit against a build-scoped declaration. - The record carries either a feature corridor side or one exact dimension's relative - lane, never page coordinates. The matching feature/request in :class:`PartModel` + The record carries a feature corridor side, one exact dimension's corridor side, + or one exact dimension's relative lane, never page coordinates. The matching feature/request in :class:`PartModel` contains the resolved value used by the renderer; retaining this separate intent record makes generated replay and assessment evidence explicit without turning layout policy into engineering meaning. @@ -2742,8 +2742,12 @@ def __post_init__(self) -> None: if (self.side is None) == (self.lane is None): raise ValueError("layout override requires exactly one of side or lane") if self.side is not None: - if self.parameter_id is not None: - raise ValueError("a side override targets a declaration, not a parameter") + if self.parameter_id is not None and ( + not isinstance(self.parameter_id, str) + or not self.parameter_id.strip() + or self.parameter_id != self.parameter_id.strip() + ): + raise ValueError("dimension side override requires a non-empty parameter_id") validate_placement_intent(None, self.side, owner="layout override") return if not isinstance(self.parameter_id, str) or not self.parameter_id.strip(): @@ -2901,6 +2905,24 @@ def __post_init__(self) -> None: ) feature = self.features[index] if override.side is not None: + if override.parameter_id is not None: + matching_side = [ + request + for request in ( + *self.requested_dimensions, + *(self.authored_dimensions or ()), + ) + if request.feature is feature + and request.role == override.parameter_id + and request.side == override.side + ] + if len(matching_side) != 1: + raise ValueError( + f"layout override {override.declaration_id!r} records side " + f"{override.side!r} for {override.parameter_id!r}, but found " + f"{len(matching_side)} matching resolved dimension intents" + ) + continue resolved = getattr(feature, "side", None) if resolved != override.side: raise ValueError( diff --git a/src/draftwright/reporting.py b/src/draftwright/reporting.py index ee181362..f827b3db 100644 --- a/src/draftwright/reporting.py +++ b/src/draftwright/reporting.py @@ -2197,7 +2197,18 @@ def _declared_layout( ) feature = model.features[feature_index] if override.side is not None: - resolved = getattr(feature, "side", None) + if override.parameter_id is None: + resolved = getattr(feature, "side", None) + else: + matches = [ + request + for request in ( + *model.requested_dimensions, + *(model.authored_dimensions or ()), + ) + if request.feature is feature and request.role == override.parameter_id + ] + resolved = matches[0].side if len(matches) == 1 else None if resolved != override.side: raise ReportUnavailableError( f"layout override {override.declaration_id!r} did not resolve to its recorded side" @@ -2210,6 +2221,8 @@ def _declared_layout( "intent_class": "layout-only", "status": "applied", } + if override.parameter_id is not None: + row["parameter_id"] = override.parameter_id else: matches = [ request diff --git a/src/draftwright/sheet.py b/src/draftwright/sheet.py index d111963a..5c696cd2 100644 --- a/src/draftwright/sheet.py +++ b/src/draftwright/sheet.py @@ -1651,7 +1651,8 @@ def layout_override( ) -> Sheet: """Append one bounded declaration-scoped layout override. - ``side`` selects a feature corridor. ``parameter`` + ``lane`` selects a one-based + ``side`` selects a feature corridor, or a declared dimension's corridor when + paired with ``parameter``. ``parameter`` + ``lane`` selects a one-based parallel lane for one declared referential dimension. Neither form accepts page coordinates; the shared placement solve resolves and validates the physical offset. """ diff --git a/src/draftwright/sheet_emit.py b/src/draftwright/sheet_emit.py index 35f6b03f..09fee349 100644 --- a/src/draftwright/sheet_emit.py +++ b/src/draftwright/sheet_emit.py @@ -949,9 +949,14 @@ def _layout_override_block(model) -> list[str]: lines = [] for override in model.layout_overrides: if override.side is not None: + parameter = ( + f"parameter={json.dumps(override.parameter_id)}, " + if override.parameter_id is not None + else "" + ) lines.append( "sheet.layout_override(" - f"{json.dumps(override.declaration_id)}, side={json.dumps(override.side)})" + f"{json.dumps(override.declaration_id)}, {parameter}side={json.dumps(override.side)})" ) else: lines.append( diff --git a/src/draftwright/sheet_layout_controls.py b/src/draftwright/sheet_layout_controls.py index cab1d353..22d18e26 100644 --- a/src/draftwright/sheet_layout_controls.py +++ b/src/draftwright/sheet_layout_controls.py @@ -104,9 +104,31 @@ def layout_options( f"declaration {declaration_id!r} has no declared dimension " f"{parameter_id!r} to override" ) - if not dimension_lane_supported(feature, parameter_id): + controls: dict[str, object] = {} + if dimension_lane_supported(feature, parameter_id): + controls["lane"] = { + "current": entry[0].get("lane"), + "minimum": 1, + "maximum": 8, + "meaning": "one-based drafting-spaced lane from the feature witness", + } + # Only advertise sides whose renderer consumes the authored corridor. Other + # planner-accepted sides are not an editor actuator until that renderer uses them. + if feature.kind in {"hole", "pattern", "envelope"}: + placements = sheet.dimension_options(handle, parameter)["placements"] + sides = sorted( + { + placement["side"] + for placement in placements + if placement["side"] is not None + and (entry[0].get("view") is None or placement["view"] == entry[0]["view"]) + } + ) + if sides: + controls["side"] = {"current": entry[0].get("side"), "supported_values": sides} + if not controls: raise ValueError( - f"dimension {parameter_id!r} on {feature.kind} does not expose a lane control" + f"dimension {parameter_id!r} on {feature.kind} does not expose a layout control" ) return { "schema": "draftwright.layout-options", @@ -116,14 +138,7 @@ def layout_options( "declaration_id": declaration_id, "feature_kind": feature.kind, "parameter_id": parameter_id, - "controls": { - "lane": { - "current": entry[0].get("lane"), - "minimum": 1, - "maximum": 8, - "meaning": "one-based drafting-spaced lane from the feature witness", - } - }, + "controls": controls, } side = getattr(feature, "side", None) if side not in PLACEMENT_SIDES: @@ -186,7 +201,7 @@ def validate_layout_override( { "code": "unsupported_control", "controls": sorted(unsupported_controls), - "message": "layout_override accepts only side, or parameter with lane", + "message": "layout_override accepts only side, or parameter with side or lane", } ] return result @@ -206,14 +221,6 @@ def validate_layout_override( } ] return result - if side is not None and parameter is not None: - result["issues"] = [ - { - "code": "invalid_control_combination", - "message": "parameter selects a dimension lane and cannot accompany side", - } - ] - return result feature = sheet._features[sheet._index_of_token(token)] try: options = sheet.layout_options(declaration_id, parameter=parameter) @@ -227,8 +234,18 @@ def validate_layout_override( ] return result result["options"] = options + controls = cast(dict[str, object], options["controls"]) if side is not None: - supported = options["controls"]["side"]["supported_values"] # type: ignore[index] + side_options = controls.get("side") + if side_options is None: + result["issues"] = [ + { + "code": "unsupported_control", + "message": "dimension does not expose a side control", + } + ] + return result + supported = cast(list[str], cast(dict[str, object], side_options)["supported_values"]) if side not in supported: result["issues"] = [ { @@ -242,6 +259,14 @@ def validate_layout_override( return result else: assert parameter is not None + if "lane" not in controls: + result["issues"] = [ + { + "code": "unsupported_control", + "message": "dimension does not expose a lane control", + } + ] + return result if isinstance(lane, bool) or not isinstance(lane, int) or not 1 <= lane <= 8: result["issues"] = [ { @@ -273,23 +298,33 @@ def layout_override( coordinates; the shared placement solve resolves and validates the physical offset. """ - key = (declaration_id, parameter) - if any((row.declaration_id, row.parameter_id) == key for row in sheet._layout_overrides): - raise ValueError(f"layout target {key!r} already has a layout override") validation = sheet.validate_layout_override( declaration_id, side=side, parameter=parameter, lane=lane ) if not validation["supported"]: issues = cast(list[dict[str, object]], validation["issues"]) raise ValueError(str(issues[0]["message"])) + options = cast(dict[str, object], validation["options"]) + parameter_id = cast(str | None, options.get("parameter_id")) + key = (declaration_id, parameter_id) + if any((row.declaration_id, row.parameter_id) == key for row in sheet._layout_overrides): + raise ValueError(f"layout target {key!r} already has a layout override") token = sheet._declaration_token(declaration_id) if side is not None: - index = sheet._index_of_token(token) - sheet._replace_feature(index, replace(sheet._features[index], side=side)) - sheet._layout_overrides.append(LayoutOverride(declaration_id, side)) + if parameter is None: + index = sheet._index_of_token(token) + sheet._replace_feature(index, replace(sheet._features[index], side=side)) + sheet._layout_overrides.append(LayoutOverride(declaration_id, side)) + else: + assert parameter_id is not None + entry = sheet._dimension_entry_for_layout(token, parameter_id) + assert entry is not None + entry[0]["side"] = side + sheet._layout_overrides.append( + LayoutOverride(declaration_id, side=side, parameter_id=parameter_id) + ) else: - options = cast(dict[str, object], validation["options"]) - parameter_id = cast(str, options["parameter_id"]) + assert parameter_id is not None entry = sheet._dimension_entry_for_layout(token, parameter_id) assert entry is not None and lane is not None entry[0]["lane"] = lane diff --git a/tests/test_issue_1466_semantic_sides.py b/tests/test_issue_1466_semantic_sides.py index 66ff0eec..2c942e3c 100644 --- a/tests/test_issue_1466_semantic_sides.py +++ b/tests/test_issue_1466_semantic_sides.py @@ -1,5 +1,6 @@ """Preserve GRM04 dimension meaning when authored side hints change placement.""" +import json from collections import Counter from dataclasses import replace from pathlib import Path @@ -7,6 +8,7 @@ import pytest from _drawing_helpers import execute_sheet_script_without_export from build123d import Box, Cylinder, Pos +from jsonschema.validators import validator_for from draftwright import Sheet, build_drawing from draftwright.audit import compare_measurements @@ -194,6 +196,64 @@ def test_native_hole_routes_and_height_honour_the_requested_side(kind, side): assert not any(issue.code.endswith("_dropped") for issue in drawing.lint()) +def test_editor_side_override_moves_declared_hole_and_height() -> None: + part = Box(20, 40, 50) - Cylinder(2, 20, rotation=(0, 90, 0)) + sheet = Sheet(part, scale=2).authored_dimensions() + bore = sheet.hole(diameter=4, depth=20, at=(0, 0, 0), axis="x").identify("bore") + sheet.dimension(bore, "bore.diameter") + envelope = sheet.envelope().identify("overall") + sheet.dimension(envelope, "height.length") + + for declaration, parameter in (("bore", "bore.diameter"), ("overall", "height.length")): + options = sheet.layout_options(declaration, parameter=parameter) + assert {"left", "right"} <= set(options["controls"]["side"]["supported_values"]) + assert sheet.validate_layout_override(declaration, parameter=parameter, side="left")[ + "supported" + ] + sheet.layout_override(declaration, parameter=parameter, side="left") + + model = sheet.model() + assert { + (row.declaration_id, row.parameter_id, row.side) for row in model.layout_overrides + } == { + ("bore", "bore.diameter", "left"), + ("overall", "height.length", "left"), + } + source = emit_sheet_script( + model, "part = source_part", "editor-side", title="editor-side", number="2211" + ) + assert 'sheet.layout_override("bore", parameter="bore.diameter", side="left")' in source + replayed = {"source_part": part} + execute_sheet_script_without_export(source, "", replayed) + assert replayed["sheet"].model().layout_overrides == model.layout_overrides + + drawing = sheet.build() + assert { + (row["declaration_id"], row["parameter_id"], row["control"], row["resolved_value"]) + for row in drawing.report()["layout"]["overrides"] + } == { + ("bore", "bore.diameter", "side", "left"), + ("overall", "height.length", "side", "left"), + } + schema = json.loads( + ( + Path(__file__).parents[1] / "docs/reference/draftwright-report-v8.schema.json" + ).read_text() + ) + assert list(validator_for(schema)(schema).iter_errors(drawing.report())) == [] + bore_labels = [ + annotation + for name, annotation in drawing.iter_annotations() + if any(key["parameter_id"] == "bore.diameter" for key in drawing.measurement_keys(name)) + ] + assert len(bore_labels) == 1 + left, _, right, _ = drawing.view_bounds("side") + assert bore_labels[0].bounding_box().max.X < (left + right) / 2 + height = drawing.get_annotation("dim_height").bounding_box() + front_left, _, _, _ = drawing.view_bounds("front") + assert height.max.X < front_left + + def test_a_full_authored_side_is_reported_instead_of_using_the_other_side(monkeypatch): import draftwright.annotations.holes as holes diff --git a/tests/test_layout_override_lane_issue_1757.py b/tests/test_layout_override_lane_issue_1757.py index 72fad550..0701bd6d 100644 --- a/tests/test_layout_override_lane_issue_1757.py +++ b/tests/test_layout_override_lane_issue_1757.py @@ -60,13 +60,17 @@ def test_lane_capability_targets_one_declared_parameter() -> None: ] is True ) + unsupported_side = sheet.validate_layout_override( + "declaration:slot", parameter="slot_width.length", side="left" + ) + assert unsupported_side["issues"][0]["code"] == "unsupported_control" missing_parameter = sheet.validate_layout_override("declaration:slot", lane=4) assert missing_parameter["issues"][0]["code"] == "invalid_control_combination" mixed_controls = sheet.validate_layout_override( "declaration:slot", side="above", parameter="not-a-parameter" ) - assert mixed_controls["issues"][0]["code"] == "invalid_control_combination" + assert mixed_controls["issues"][0]["code"] == "unsupported_declaration" invalid_lane = sheet.validate_layout_override( "declaration:slot", parameter="slot_width.length", lane=0 ) @@ -151,7 +155,7 @@ def test_requested_dimension_rejects_invalid_and_location_lanes() -> None: ("kwargs", "message"), [ ({}, "exactly one of side or lane"), - ({"side": "above", "parameter_id": "slot_width.length"}, "not a parameter"), + ({"side": "above", "parameter_id": " slot_width.length "}, "non-empty parameter_id"), ({"lane": 2}, "non-empty parameter_id"), ({"parameter_id": " slot_width.length ", "lane": 2}, "surrounding whitespace"), ({"parameter_id": "slot_width.length", "lane": 9}, "integer from 1 to 8"), @@ -181,8 +185,15 @@ def test_layout_options_refuses_missing_duplicate_and_unsupported_dimensions() - "declaration:hole", provenance="detected-geometry" ) missing.dimension(hole, "bore.diameter") - with pytest.raises(ValueError, match="does not expose a lane control"): - missing.layout_options("declaration:hole", parameter="bore.diameter") + assert ( + "side" in missing.layout_options("declaration:hole", parameter="bore.diameter")["controls"] + ) + assert ( + missing.validate_layout_override("declaration:hole", parameter="bore.diameter", lane=2)[ + "issues" + ][0]["code"] + == "unsupported_control" + ) duplicate = _slot_sheet() duplicate.dimension(duplicate.model().features[0], "slot_width.length") diff --git a/tests/test_layout_override_side_issue_1757.py b/tests/test_layout_override_side_issue_1757.py index 27fefede..179037fd 100644 --- a/tests/test_layout_override_side_issue_1757.py +++ b/tests/test_layout_override_side_issue_1757.py @@ -101,7 +101,7 @@ def test_validation_rejects_unknown_and_ambiguous_controls_without_changing_inte { "code": "unsupported_control", "controls": ["x", "y"], - "message": "layout_override accepts only side, or parameter with lane", + "message": "layout_override accepts only side, or parameter with side or lane", } ] for controls in ({}, {"side": "above", "lane": 2}):