(causeway) 01/03: docs(openspec): plan action button layout improvements

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch htmx
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 835b2d43b23167a43b621502344a70170e35345e
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Aug 30 16:34:27 2026 +0200

    docs(openspec): plan action button layout improvements
---
 .../improve-action-button-layout/.openspec.yaml    |  2 +
 .../changes/improve-action-button-layout/design.md | 62 ++++++++++++++++++++++
 .../improve-action-button-layout/proposal.md       | 31 +++++++++++
 .../specs/domain-web-components/spec.md            | 18 +++++++
 .../generic-htmx-web-component-viewer/spec.md      | 19 +++++++
 .../changes/improve-action-button-layout/tasks.md  | 16 ++++++
 6 files changed, 148 insertions(+)

diff --git a/openspec/changes/improve-action-button-layout/.openspec.yaml b/openspec/changes/improve-action-button-layout/.openspec.yaml
new file mode 100644
index 00000000000..88ea4823207
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-30
diff --git a/openspec/changes/improve-action-button-layout/design.md b/openspec/changes/improve-action-button-layout/design.md
new file mode 100644
index 00000000000..1104d5fceff
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/design.md
@@ -0,0 +1,62 @@
+## Context
+
+A property-associated `<cw-action>` remains a direct child of `<cw-property>` while the rendered property row lives inside the generated `.causeway-member-primary` wrapper.
+Current structural styles make the primary wrapper consume the full flex row, so associated actions begin at the host's logical start rather than at the property field column.
+The Petclinic owner page separately authors `<cw-object-header>` and an object-action toolbar as consecutive grid rows, so the delete action necessarily appears below the title.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Align property-associated actions with the effective property field column at wide widths.
+- Collapse associated actions to the same logical start as a stacked field at narrow widths.
+- Compose the Petclinic owner title and object-level action in one application-owned responsive heading row.
+- Preserve action semantics, focus, invocation, toolkit selection, and component ownership.
+
+**Non-Goals:**
+
+- Change GraphQL action metadata or invocation behavior.
+- Move Petclinic-specific title composition into `<cw-object-header>` or `<cw-object>`.
+- Change collection-associated action placement.
+- Introduce a new public component or application layout API.
+
+## Decisions
+
+### Use host-grid placement for property-associated actions
+
+The foundation structural stylesheet will make a `<cw-property>` with associated actions use a grid whose label and field tracks match the rendered property grid.
+The generated `.causeway-member-primary` will span the complete grid, while each associated action begins in the field track.
+The cohesive theme will mirror its effective property columns on the associated-action host and will reset action placement to the first track when property content stacks responsively.
+This keeps placement in component-owned styles and avoids application-specific offsets.
+
+A margin or padding offset was rejected because the effective label track may be responsive or expressed as `minmax(...)`, making arithmetic offsets brittle.
+Moving authored actions into the generated property markup was rejected because it would complicate light-DOM ownership, mutation observation, and semantic event ancestry for a cosmetic change.
+
+### Keep object title composition application-owned
+
+The Petclinic owner page will wrap `<cw-object-header>` and its delete-action toolbar in a semantic application heading container.
+Petclinic application CSS will lay out that container as a wrapping flex row, remove the inner header's standalone bottom spacing and border in that context, and place the shared divider on the wrapper.
+At narrow widths the row may wrap while retaining title-before-action document order.
+
+Changing `<cw-object-header>` to accept or discover unrelated actions was rejected because object-level placement is application layout policy and existing pages may require other arrangements.
+
+### Verify structure at foundation and Petclinic levels
+
+Foundation tests will assert synchronized structural styles and wide/narrow property-associated-action placement hooks.
+Petclinic resource or browser coverage will assert that the owner heading contains the object header followed by the delete action and that the property-associated update action remains nested beneath its property.
+
+## Risks / Trade-offs
+
+- [Risk] Theme and structural property-column definitions can drift and misalign associated actions. → Reuse the same variables and assert both baseline and cohesive-theme selectors in component-style tests.
+- [Risk] Several actions associated with one property may occupy additional grid rows. → Preserve logical order, spacing, and wrapping behavior, and keep the field-column start for every action.
+- [Risk] A long title and action may not fit on one line. → Allow the application heading container to wrap in document order without overlap or horizontal overflow.
+
+## Migration Plan
+
+No migration is required.
+Applications using documented semantic markup receive the corrected property-associated placement through foundation styles.
+The Petclinic title-row change is isolated to its packaged HTML and application stylesheet and can be rolled back independently.
+
+## Open Questions
+
+None.
diff --git a/openspec/changes/improve-action-button-layout/proposal.md b/openspec/changes/improve-action-button-layout/proposal.md
new file mode 100644
index 00000000000..49a9030f604
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/proposal.md
@@ -0,0 +1,31 @@
+## Why
+
+Associated and object-level action buttons currently sit on separate rows that weaken their visual relationship to the field or object they operate on.
+The Petclinic reference page should demonstrate a more compact, intentional action layout while preserving semantic component ownership.
+
+## What Changes
+
+- Align property-associated actions with the property field/value column rather than below the complete property row.
+- Allow property-associated action placement to collapse responsively without overlap or horizontal overflow.
+- Move the Petclinic owner object-level delete action into the title row immediately after the object header.
+- Keep object-title/action composition application-owned while ensuring semantic web components do not force unnecessary full-line placement.
+- Add focused foundation and Petclinic regression coverage for the revised placements.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `domain-web-components`: Refine associated-action and component flow presentation requirements for responsive member composition.
+- `generic-htmx-web-component-viewer`: Refine Petclinic custom-page and visual acceptance requirements for application-owned inline title actions.
+
+## Impact
+
+- Foundation structural styles and synchronized installable styles.
+- Foundation component-style and property-associated-action regression tests.
+- Petclinic `petclinic.PetOwner.html` application layout and application stylesheet.
+- Petclinic browser and/or resource-page regression assertions.
+- No GraphQL, semantic event, action invocation, or public Java API changes.
diff --git a/openspec/changes/improve-action-button-layout/specs/domain-web-components/spec.md b/openspec/changes/improve-action-button-layout/specs/domain-web-components/spec.md
new file mode 100644
index 00000000000..132055bf362
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/specs/domain-web-components/spec.md
@@ -0,0 +1,18 @@
+## ADDED Requirements
+
+### Requirement: Field-aligned property-associated actions
+The component library SHALL place actions authored directly beneath a property in visual association with that property's field rather than its label while preserving semantic action behavior and light-DOM ownership.
+
+#### Scenario: Associated action renders at wide width
+- **WHEN** a property with a left-positioned label renders one or more associated actions at a wide layout width
+- **THEN** each associated action begins at the logical start of the property's field column
+- **AND** the label column remains free of action controls
+
+#### Scenario: Associated action renders at narrow width
+- **WHEN** responsive presentation stacks the property label and field
+- **THEN** associated actions begin at the same logical start as the stacked field
+- **AND** controls do not overlap, clip, or introduce horizontal page overflow
+
+#### Scenario: Associated action is activated
+- **WHEN** a user activates a field-aligned associated action
+- **THEN** the established semantic action request, toolkit selection, focus, disabled state, tooltip, and invocation behavior remain unchanged
diff --git a/openspec/changes/improve-action-button-layout/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/improve-action-button-layout/specs/generic-htmx-web-component-viewer/spec.md
new file mode 100644
index 00000000000..08ff05da20b
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/specs/generic-htmx-web-component-viewer/spec.md
@@ -0,0 +1,19 @@
+## ADDED Requirements
+
+### Requirement: Application-owned Petclinic object heading actions
+The Petclinic owner custom page SHALL compose its object title and object-level actions in an application-owned responsive heading row without changing semantic object-header or action component contracts.
+
+#### Scenario: Owner page renders at wide width
+- **WHEN** a Petclinic owner route renders with sufficient inline space
+- **THEN** the remove-owner action appears immediately after the object title in the same heading row
+- **AND** the page does not place that object-level action in a separate toolbar row below the title
+
+#### Scenario: Owner heading has insufficient width
+- **WHEN** the title and object-level action cannot fit on one line
+- **THEN** the application heading row wraps in title-before-action document order
+- **AND** the title and action remain readable, operable, and free of overlap or horizontal page overflow
+
+#### Scenario: Application owns heading placement
+- **WHEN** the owner page composes the title and object-level action
+- **THEN** placement is defined by the Petclinic HTML resource and application stylesheet
+- **AND** `<cw-object-header>` and `<cw-action>` retain their established framework-neutral rendering and semantic behavior
diff --git a/openspec/changes/improve-action-button-layout/tasks.md b/openspec/changes/improve-action-button-layout/tasks.md
new file mode 100644
index 00000000000..c2ca602f7df
--- /dev/null
+++ b/openspec/changes/improve-action-button-layout/tasks.md
@@ -0,0 +1,16 @@
+## 1. Foundation associated-action layout
+
+- [ ] 1.1 Update the synchronized structural styles so property-associated actions start in the property field column.
+- [ ] 1.2 Update cohesive-theme wide and responsive rules so associated actions follow the effective field start when property content stacks.
+- [ ] 1.3 Add foundation regression assertions for synchronized wide and narrow associated-action placement.
+
+## 2. Petclinic object heading layout
+
+- [ ] 2.1 Compose the Petclinic owner object header and delete action in one application-owned heading container.
+- [ ] 2.2 Add responsive Petclinic application styles for inline title/action placement and wrapping.
+- [ ] 2.3 Add Petclinic resource or browser regression assertions for title/action document structure and placement hooks.
+
+## 3. Verification
+
+- [ ] 3.1 Run the foundation test suite.
+- [ ] 3.2 Run the applicable Petclinic module tests.