(causeway) 10/19: docs(openspec): plan PetOwner layout simplification

[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 8621de09f3d543f024e224e3626a7d0c68a2f68c
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sun Sep 6 10:06:53 2026 +0100

    docs(openspec): plan PetOwner layout simplification
---
 .../.openspec.yaml                                 |  2 +
 .../simplify-petowner-declarative-layout/design.md | 76 ++++++++++++++++++++++
 .../proposal.md                                    | 31 +++++++++
 .../specs/domain-web-components/spec.md            | 44 +++++++++++++
 .../generic-htmx-web-component-viewer/spec.md      | 50 ++++++++++++++
 .../specs/generic-vue-web-component-viewer/spec.md | 50 ++++++++++++++
 .../simplify-petowner-declarative-layout/tasks.md  | 25 +++++++
 7 files changed, 278 insertions(+)

diff --git a/openspec/changes/simplify-petowner-declarative-layout/.openspec.yaml b/openspec/changes/simplify-petowner-declarative-layout/.openspec.yaml
new file mode 100644
index 00000000000..1a62d62b5b5
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06
diff --git a/openspec/changes/simplify-petowner-declarative-layout/design.md b/openspec/changes/simplify-petowner-declarative-layout/design.md
new file mode 100644
index 00000000000..31e4978b883
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/design.md
@@ -0,0 +1,76 @@
+## Context
+
+The PetOwner HTMX and Vue pages currently place semantic foundation components inside three application-owned macro-layout divs and several card sections.
+Inside the details column, full-width fieldsets are also wrapped in twelve-span rows and columns that add no layout choice.
+Inside the collections column, application sections repeat the semantic section and heading already rendered by `<cw-collection>`.
+
+Foundation rows already provide twelve tracks and responsive stacking, while columns already accept fieldsets, collections, and metadata.
+The missing composition needed for the page is a direct tabgroup child in a column, which is also a natural correspondence to a `layout.xml` column containing tabs.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the visible PetOwner macro layout directly legible from semantic custom elements.
+- Preserve the existing one-third/two-thirds wide layout through spans 4 and 8.
+- Let shared column layout provide vertical child spacing and responsive stacking.
+- Preserve Identity/Metadata tabs, Contact and Details fieldsets, Pets and Visits collections, Agreement reading, actions, previews, and host parity.
+- Keep strict direct-child validation and bounded diagnostics.
+
+**Non-Goals:**
+
+- Allowing arbitrary HTML children in rows, columns, fieldsets, or tabs.
+- Turning declarative components into general-purpose CSS layout primitives.
+- Changing domain metadata, collection ordering, authorization, PDF behavior, routes, or application ownership.
+- Replacing object-heading or action-result structure that is outside the macro object grid.
+- Changing generic object-page composition outside this representative sample.
+
+## Decisions
+
+### Extend the column grammar only for tabgroups
+
+`<cw-column>` will accept direct `<cw-tabgroup>` children alongside fieldsets, collections, and metadata.
+It will not accept arbitrary divs, sections, properties, actions, nested columns, or rows.
+This narrow extension is preferred over allowing generic children because it preserves fail-closed grammar and corresponds to a meaningful layout structure.
+
+### Make columns vertical layout containers
+
+A connected layout column will stack its valid children in authored order with the shared layout gap and start alignment.
+Its existing span behavior remains responsible for horizontal placement within a row.
+This is preferred over retaining Petclinic details and collections classes solely to add `display: grid` and a gap.
+
+### Use one shared row for the macro object grid
+
+The application-owned details and collections wrappers will become direct columns with spans 4 and 8 under one row.
+At the shared narrow breakpoint, both columns will span all tracks and retain details-before-collections document order.
+The sample will adopt the shared foundation breakpoint rather than retaining a separate Petclinic-only object-grid breakpoint.
+
+### Remove only semantically redundant wrappers
+
+Contact and Details will become direct fieldset children of the details column because their former twelve-span wrappers did not affect layout.
+The rows inside each tab remain because `<cw-tab>` intentionally accepts only rows.
+Pets and Visits will become direct collection children because each collection already renders its own labelled semantic section.
+Agreement will become a direct named fieldset containing the PDF property, because a standalone property is not a valid column child and the group title remains useful.
+
+### Preserve user-facing labels through the semantic owner
+
+When an outer application heading is removed, the corresponding foundation component will carry the user-facing panel label.
+Collection descriptions, actions, previews, paging, sorting, and filtering remain unchanged.
+The simplification MUST NOT add a second title or infer domain identity from presentation text.
+
+## Risks / Trade-offs
+
+- [Risk] Broadening column children could weaken the strict grammar. → Mitigation: add only `cw-tabgroup`, retain unsupported-child hiding and diagnostics, and test rejection of all other child kinds.
+- [Risk] Shared column gaps could alter existing layouts with multiple children. → Mitigation: use the existing shared layout gap token, preserve authored order, and run foundation and browser visual geometry coverage.
+- [Risk] Removing outer sections could change accessible headings or labels. → Mitigation: verify each collection's internal labelled section and use explicit representative labels where needed.
+- [Risk] Adopting the shared 48rem breakpoint changes the former Petclinic-only 60rem transition. → Mitigation: verify no overflow across intermediate and narrow widths and document that foundation owns responsive behavior.
+- [Risk] Generated Vue markup could diverge from HTMX after simplification. → Mitigation: assert equivalent direct-child trees and regenerate production assets through the established build.
+
+## Migration Plan
+
+Extend and test the foundation column contract first, then simplify HTMX and Vue declarations, remove now-unused sample CSS selectors, update tests and documentation, regenerate Vue assets, and run native and Vaadin browser checks.
+Rollback restores the wrapper declarations and CSS while removing tabgroup from the column allow-list; no data or API migration is required.
+
+## Open Questions
+
+None.
diff --git a/openspec/changes/simplify-petowner-declarative-layout/proposal.md b/openspec/changes/simplify-petowner-declarative-layout/proposal.md
new file mode 100644
index 00000000000..7de5e07bfa2
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/proposal.md
@@ -0,0 +1,31 @@
+## Why
+
+The PetOwner pages still use application-specific grid, details, collections, and card wrappers around layout that `<cw-row>`, `<cw-column>`, `<cw-fieldset>`, and `<cw-collection>` can represent directly.
+This obscures the intended declarative layout model and leaves HTMX and Vue examples carrying avoidable markup and CSS.
+
+## What Changes
+
+- Allow `<cw-column>` to contain a direct `<cw-tabgroup>` in addition to fieldsets, collections, and metadata, matching practical column composition and the conceptual `layout.xml` hierarchy.
+- Replace the PetOwner macro grid and its details and collections wrapper divs with one `<cw-row>` containing `span="4"` and `span="8"` columns.
+- Remove redundant full-width row/column wrappers around non-tabbed fieldsets.
+- Remove application `<section>` card wrappers where `<cw-collection>` already supplies the semantic collection section and heading.
+- Represent Agreement as a named `<cw-fieldset>` containing the agreement property.
+- Preserve the Identity/Metadata tabs, authoritative member behavior, collection actions and previews, PDF reader, responsive order, two-column ratio, application shell, context, routing, and HTMX/Vue parity.
+- Reduce Petclinic-specific CSS and tests to the behavior that is not already owned by foundation layout components.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `domain-web-components`: Permit a tab group as a valid direct column child while retaining strict fail-closed layout grammar.
+- `generic-htmx-web-component-viewer`: Simplify the HTMX PetOwner page to use foundation layout components for its macro layout and semantic collection panels.
+- `generic-vue-web-component-viewer`: Apply the same simplified declarative PetOwner structure without Vue-owned layout behavior.
+
+## Impact
+
+The change affects foundation column validation and tests, shared layout documentation, HTMX and Vue PetOwner declarations and acceptance tests, Petclinic application CSS, and generated Vue assets.
+It adds no GraphQL fields, domain behavior, host-framework state, dependency, or compatibility alias.
diff --git a/openspec/changes/simplify-petowner-declarative-layout/specs/domain-web-components/spec.md b/openspec/changes/simplify-petowner-declarative-layout/specs/domain-web-components/spec.md
new file mode 100644
index 00000000000..79ff04ba773
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/specs/domain-web-components/spec.md
@@ -0,0 +1,44 @@
+## MODIFIED Requirements
+
+### Requirement: Declarative twelve-column row layout
+
+The foundation SHALL register `<cw-row>` and `<cw-column>` as framework-neutral layout containers.
+A row MUST accept only direct column children, and a column MUST accept direct fieldset, collection, metadata, or tabgroup children without taking ownership of their domain behavior.
+A column SHALL stack multiple valid children in authored order with shared bounded layout spacing.
+
+#### Scenario: Row contains columns
+
+- **WHEN** a row contains valid columns whose normalized spans total no more than twelve
+- **THEN** a wide presentation places them on a twelve-track grid according to authored order and span
+- **AND** a narrow presentation stacks them in authored order without horizontal document overflow
+
+#### Scenario: Column declares a valid span
+
+- **WHEN** `<cw-column span="x">` declares an integer from 1 through 12
+- **THEN** it occupies exactly that many wide-layout tracks
+- **AND** the authored value remains inspectable as the column contract
+
+#### Scenario: Column contains multiple layout children
+
+- **WHEN** a column directly contains fieldsets, collections, metadata, or tabgroups
+- **THEN** it presents them vertically in authored order with the shared layout gap and start alignment
+- **AND** each child retains ownership of its semantic and domain behavior
+
+#### Scenario: Column contains a tab group
+
+- **WHEN** a column directly contains `<cw-tabgroup>`
+- **THEN** the tab group remains a valid connected child with its existing tab, panel, focus, mutation, and responsive behavior
+- **AND** the column does not translate or reconstruct the tab structure
+
+#### Scenario: Column span is absent or invalid
+
+- **WHEN** span is absent
+- **THEN** the column uses twelve tracks
+- **WHEN** span is not an integer from 1 through 12
+- **THEN** the column safely uses twelve tracks and emits a bounded diagnostic
+
+#### Scenario: Row or column contains an unsupported child
+
+- **WHEN** a row or column has a direct child outside its allowed element set
+- **THEN** that child is excluded from layout presentation and a bounded diagnostic is emitted
+- **AND** valid siblings remain connected and usable
diff --git a/openspec/changes/simplify-petowner-declarative-layout/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/simplify-petowner-declarative-layout/specs/generic-htmx-web-component-viewer/spec.md
new file mode 100644
index 00000000000..7701f072b93
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/specs/generic-htmx-web-component-viewer/spec.md
@@ -0,0 +1,50 @@
+## MODIFIED Requirements
+
+### Requirement: HTMX Petclinic declarative layout demonstration
+
+The HTMX Petclinic application SHALL demonstrate application-authored `<cw-row>`, `<cw-column>`, `<cw-fieldset>`, `<cw-tabgroup>`, `<cw-tab>`, and `<cw-metadata>` composition beneath its existing object context and interaction controller.
+The PetOwner macro layout SHALL use one direct row containing details and collections columns with spans 4 and 8 rather than application grid, details, or collections wrapper divs.
+The demonstrated tab group SHALL contain an initial **Identity** tab followed by a **Metadata** tab and SHALL NOT retain the artificial **Layout help** tab or placeholder content.
+HTMX templates MUST NOT duplicate foundation span, column spacing, responsive stacking, tab, metadata-discovery, collection-section, or action-menu behavior.
+
+#### Scenario: Petclinic layout renders wide and narrow
+
+- **WHEN** the demonstrated exact page is opened at documented wide and narrow viewports
+- **THEN** the details and collections columns use authored 4/8 spans at wide width and stack in semantic order at the shared narrow breakpoint
+- **AND** page navigation, member behavior, collection presentation, and document overflow remain correct
+
+#### Scenario: PetOwner macro composition is inspected
+
+- **WHEN** the HTMX PetOwner page source or connected direct-child tree is inspected
+- **THEN** one macro row directly owns the details and collections columns
+- **AND** no application-specific object-grid, object-details, or object-collections wrapper div is present
+
+#### Scenario: PetOwner tab composition renders
+
+- **WHEN** the PetOwner exact page reaches its presentable state
+- **THEN** the current Identity tab contains the owner's identity fields and the following Metadata tab contains `<cw-metadata>`
+- **AND** Contact and Details are direct fieldset children of the details column without redundant full-width row and column wrappers
+
+#### Scenario: Semantic collection panels render
+
+- **WHEN** the Pets and Visits collections render in the collections column
+- **THEN** each direct `<cw-collection>` supplies its own labelled semantic section, heading, description, actions, preview, rows, and paging
+- **AND** no outer application section duplicates that collection panel
+
+#### Scenario: Agreement panel renders
+
+- **WHEN** the Agreement panel renders in the collections column
+- **THEN** a direct named fieldset contains the existing agreement property and PDF reader
+- **AND** no standalone property violates the column grammar
+
+#### Scenario: User operates the HTMX tab group
+
+- **WHEN** the user changes between Identity and Metadata by pointer or keyboard
+- **THEN** foundation updates the accessible current white panel without an HTMX request or route replacement
+- **AND** the application shell and object context remain stable
+
+#### Scenario: HTMX metadata menu resolves
+
+- **WHEN** the demonstrated object's effective metadata fieldset contains associated actions
+- **THEN** `<cw-metadata>` shows exactly its authoritative properties and a heading ellipsis menu containing the authorized actions
+- **AND** HTMX does not provide hard-coded metadata member ids, action grouping, menu state, or menu positioning
diff --git a/openspec/changes/simplify-petowner-declarative-layout/specs/generic-vue-web-component-viewer/spec.md b/openspec/changes/simplify-petowner-declarative-layout/specs/generic-vue-web-component-viewer/spec.md
new file mode 100644
index 00000000000..8a47e15fd9a
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/specs/generic-vue-web-component-viewer/spec.md
@@ -0,0 +1,50 @@
+## MODIFIED Requirements
+
+### Requirement: Vue Petclinic declarative layout parity
+
+The Vue Petclinic application SHALL author the same representative `<cw-row>`, `<cw-column>`, `<cw-fieldset>`, `<cw-tabgroup>`, `<cw-tab>`, and `<cw-metadata>` structure as the HTMX reference where the corresponding exact page is reconciled.
+The PetOwner macro layout SHALL use one direct row containing details and collections columns with spans 4 and 8 rather than Vue grid, details, or collections wrapper divs.
+The reconciled tab group SHALL contain an initial **Identity** tab followed by a **Metadata** tab and SHALL NOT retain artificial placeholder content.
+Vue MUST treat those elements as custom elements and MUST NOT own their responsive, column-spacing, tab, metadata-discovery, collection-section, or action-menu state.
+
+#### Scenario: Vue layout renders
+
+- **WHEN** the reconciled exact page is opened at wide or narrow viewport width
+- **THEN** shared foundation elements preserve equivalent 4/8 columns, fieldset, tab, collection, agreement, and metadata relationships to HTMX
+- **AND** Vue wrappers do not duplicate visible members or alter semantic ordering
+
+#### Scenario: Vue PetOwner macro composition is inspected
+
+- **WHEN** the Vue PetOwner template or connected direct-child tree is inspected
+- **THEN** one macro row directly owns the details and collections columns
+- **AND** no Vue-specific object-grid, object-details, or object-collections wrapper div is present
+
+#### Scenario: Vue PetOwner tab composition renders
+
+- **WHEN** the PetOwner route page reaches its presentable state
+- **THEN** the current Identity tab contains the owner's identity fields and the following Metadata tab contains `<cw-metadata>`
+- **AND** Contact and Details are direct fieldset children of the details column without redundant full-width row and column wrappers
+
+#### Scenario: Vue semantic collection panels render
+
+- **WHEN** Pets and Visits render in the collections column
+- **THEN** direct `<cw-collection>` elements supply the same labelled semantic sections, actions, previews, rows, and paging as HTMX
+- **AND** no Vue section wrapper duplicates either collection panel
+
+#### Scenario: Vue Agreement panel renders
+
+- **WHEN** Agreement renders in the collections column
+- **THEN** a direct named fieldset contains the existing agreement property and PDF reader
+- **AND** Vue does not introduce a layout wrapper or PDF behavior
+
+#### Scenario: User operates the Vue-hosted tabs
+
+- **WHEN** pointer or keyboard input changes between Identity and Metadata
+- **THEN** foundation updates selection, focus, and the current white panel without Vue component state or route navigation
+- **AND** the application-owned route outlet and object context remain stable
+
+#### Scenario: Vue-hosted metadata resolves
+
+- **WHEN** `<cw-metadata>` consumes the current Vue route's object context with associated actions
+- **THEN** the same effective metadata properties and heading ellipsis action menu are presented as in HTMX
+- **AND** generated member components retain ordinary foundation behavior while Vue owns no menu state
diff --git a/openspec/changes/simplify-petowner-declarative-layout/tasks.md b/openspec/changes/simplify-petowner-declarative-layout/tasks.md
new file mode 100644
index 00000000000..c61f423e2e6
--- /dev/null
+++ b/openspec/changes/simplify-petowner-declarative-layout/tasks.md
@@ -0,0 +1,25 @@
+## 1. Foundation Column Composition
+
+- [ ] 1.1 Extend `<cw-column>` direct-child validation to accept `<cw-tabgroup>` while continuing to fail closed for every unsupported child.
+- [ ] 1.2 Give layout columns shared vertical stacking, start alignment, bounded gaps, and minimum-width behavior without changing span normalization.
+- [ ] 1.3 Add foundation tests for direct tabgroup composition, multiple ordered children, unsupported-child diagnostics, twelve-track spans, and responsive stacking.
+- [ ] 1.4 Update synchronized source and installable styles and declarative-layout documentation for the expanded column grammar.
+
+## 2. HTMX PetOwner Simplification
+
+- [ ] 2.1 Replace the HTMX PetOwner object-grid, details, and collections divs with one macro `<cw-row>` containing span-4 details and span-8 collections columns.
+- [ ] 2.2 Remove redundant full-width wrappers around Contact and Details while retaining required rows and columns inside tabs.
+- [ ] 2.3 Replace outer Pets and Visits card sections with direct labelled collections and represent Agreement as a direct named fieldset containing the existing property.
+- [ ] 2.4 Remove obsolete Petclinic macro-grid CSS while preserving authored order, shared responsive stacking, card presentation, collection behavior, and PDF sizing.
+- [ ] 2.5 Update HTMX source, integration, and browser assertions for direct-child grammar, wide 4/8 geometry, intermediate and narrow stacking, semantic collection headings, actions, previews, Agreement, routes, and absence of redundant wrappers.
+
+## 3. Vue PetOwner Parity
+
+- [ ] 3.1 Apply the equivalent simplified custom-element tree to the Vue PetOwner page without Vue-owned layout state.
+- [ ] 3.2 Remove equivalent obsolete Vue sample CSS and update source and browser parity assertions.
+- [ ] 3.3 Regenerate Vue production assets through the established build lifecycle.
+
+## 4. Documentation and Verification
+
+- [ ] 4.1 Update HTMX and Vue documentation to demonstrate foundation-owned macro layout and explain which application wrappers remain intentionally outside it.
+- [ ] 4.2 Run complete foundation JavaScript, HTMX, Vue, native/Vaadin, secured, responsive, accessibility, Maven packaging, RAT/license, OpenSpec, IDE, and whitespace validation.