Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/reference/draftwright-report-v8.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"],
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/reports.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
23 changes: 18 additions & 5 deletions docs/reference/sheet.md
Original file line number Diff line number Diff line change
Expand Up @@ -320,18 +320,30 @@ 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
current lane-capable slice is the linear width/length dimensions of slots. Capability is
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
Expand All @@ -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.

Expand Down
30 changes: 26 additions & 4 deletions src/draftwright/model/ir.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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():
Expand Down Expand Up @@ -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(
Expand Down
15 changes: 14 additions & 1 deletion src/draftwright/reporting.py
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
3 changes: 2 additions & 1 deletion src/draftwright/sheet.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""
Expand Down
7 changes: 6 additions & 1 deletion src/draftwright/sheet_emit.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down
91 changes: 63 additions & 28 deletions src/draftwright/sheet_layout_controls.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -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:
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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"] = [
{
Expand All @@ -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"] = [
{
Expand Down Expand Up @@ -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
Expand Down
Loading
Loading