(causeway) 01/19: docs(openspec): plan title-free preview fragments

[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 e6b4601abd3dd2b65da1b36a5e472cd4f9573d53
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Sep 4 20:28:38 2026 +0100

    docs(openspec): plan title-free preview fragments
---
 .../remove-preview-fragment-titles/.openspec.yaml  |  2 +
 .../remove-preview-fragment-titles/design.md       | 51 ++++++++++++++++++++++
 .../remove-preview-fragment-titles/proposal.md     | 27 ++++++++++++
 .../generic-htmx-web-component-viewer/spec.md      | 24 ++++++++++
 .../specs/generic-vue-web-component-viewer/spec.md | 24 ++++++++++
 .../remove-preview-fragment-titles/tasks.md        | 16 +++++++
 6 files changed, 144 insertions(+)

diff --git a/openspec/changes/remove-preview-fragment-titles/.openspec.yaml b/openspec/changes/remove-preview-fragment-titles/.openspec.yaml
new file mode 100644
index 00000000000..1d9aeef992c
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-04
diff --git a/openspec/changes/remove-preview-fragment-titles/design.md b/openspec/changes/remove-preview-fragment-titles/design.md
new file mode 100644
index 00000000000..d1ef1cc0016
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/design.md
@@ -0,0 +1,51 @@
+## Context
+
+Petclinic collection rows already render each object's authoritative title as the row's canonical link.
+Several authored preview templates also include `<cw-object-header>`, causing the expanded details area to repeat the same title and identity link.
+The duplication exists in HTMX runtime-type resources, an HTMX inline Pet preview, and Vue inline Owner, Pet, and Visit previews.
+The foundation correctly treats preview contents as application-authored composition and should not suppress arbitrary authored components.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make Petclinic previews concise by omitting repeated object titles.
+- Keep HTMX default/inline and Vue inline previews presentation-equivalent.
+- Preserve all selected fields, actions, nested collections, labels, context hydration, and lifecycle behavior.
+- Assert that live previews contain no `<cw-object-header>` while remaining useful.
+
+**Non-Goals:**
+
+- Removing page-level `<cw-object-header>` components.
+- Changing `<cw-preview>`, `<cw-object-header>`, collection rows, canonical object links, or host resolver behavior.
+- Preventing applications from deliberately authoring an object header in other previews.
+- Inferring title elements from arbitrary markup or stripping supplied HTML at runtime.
+
+## Decisions
+
+### Change authored composition rather than foundation rendering
+
+Remove explicit `<cw-object-header>` declarations from the sample's preview templates.
+The row remains the authoritative title and navigation surface, while preview bodies begin with the selected detailed properties or actions.
+
+Runtime suppression was rejected because `<cw-preview>` must preserve safe application-authored composition and cannot assume that every object header is redundant in every host layout.
+
+### Cover every Petclinic preview source
+
+Update all three HTMX runtime-type preview resources, the HTMX inline Pet preview, both Vue Home previews, and both Vue PetOwner previews.
+Update the foundation usage example to demonstrate the preferred concise composition.
+
+Changing only the preview visible in the supplied page was rejected because it would leave framework and inline/default inconsistencies.
+
+### Verify absence and retained content
+
+Source-level integration tests will verify default preview resources have no object header.
+Browser tests will verify live Owner, Pet, and Visit previews omit `<cw-object-header>` while representative properties, actions, or nested collections still render.
+
+Text-only screenshot assertions were rejected because the same title remains correctly visible in the owning row and would not identify its source.
+
+## Risks / Trade-offs
+
+- [Preview context might appear less identifiable in isolation] → The live preview is structurally attached to its titled row, and its section keeps a type-specific accessible label.
+- [Tests could confuse page and preview headers] → Scope selectors to `cw-preview[data-causeway-preview-live]`.
+- [Vue source and packaged assets could drift] → Rebuild the Vue frontend through its established Maven lifecycle and verify packaged parity.
diff --git a/openspec/changes/remove-preview-fragment-titles/proposal.md b/openspec/changes/remove-preview-fragment-titles/proposal.md
new file mode 100644
index 00000000000..0ee1f7ddd8a
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/proposal.md
@@ -0,0 +1,27 @@
+## Why
+
+Collection rows already display and link the authoritative object title beside their preview disclosure.
+Repeating that title through `<cw-object-header>` inside the expanded preview adds visual noise without useful information.
+
+## What Changes
+
+- Remove `<cw-object-header>` from Petclinic's HTMX default and inline preview fragments.
+- Remove `<cw-object-header>` from the equivalent Vue inline preview fragments.
+- Keep page-level object headers and the preview's selected properties, actions, nested collections, context, accessibility label, and lifecycle unchanged.
+- Update documentation and regression coverage to establish concise, title-free preview composition.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `generic-htmx-web-component-viewer`: Petclinic default and inline preview fragments omit the redundant object header/title while preserving useful preview content.
+- `generic-vue-web-component-viewer`: Vue's authored Petclinic previews preserve HTMX parity without repeating row titles inside expanded content.
+
+## Impact
+
+Affected files are Petclinic HTMX preview resources and page templates, Vue Petclinic page components and generated assets, preview documentation examples, and HTMX/Vue acceptance tests.
+No foundation component contract, GraphQL query, identity, authorization, routing, preview lifecycle, or renderer qualification changes.
diff --git a/openspec/changes/remove-preview-fragment-titles/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/remove-preview-fragment-titles/specs/generic-htmx-web-component-viewer/spec.md
new file mode 100644
index 00000000000..20eefd65f02
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/specs/generic-htmx-web-component-viewer/spec.md
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Concise Petclinic preview composition
+
+The HTMX Petclinic application SHALL keep each collection row's authoritative title and canonical object link in the row and SHALL omit a repeated `<cw-object-header>` from the expanded preview body.
+Title-free preview composition MUST preserve the selected detail members, actions, nested collections, context hydration, accessible preview label, and lifecycle behavior.
+
+#### Scenario: Runtime-type default preview expands
+
+- **WHEN** an Owner, Pet, or Visit row expands an authored runtime-type preview resource
+- **THEN** the live preview contains no `<cw-object-header>` and does not repeat the row title
+- **AND** its declared detailed properties, actions, or nested collections remain available
+
+#### Scenario: Inline Pet preview expands
+
+- **WHEN** the PetOwner page expands its inline Pet preview
+- **THEN** the live preview begins with useful Pet details rather than a repeated object header
+- **AND** editable notes, the preview action, and nested visits remain available under the selected row context
+
+#### Scenario: Maintainer inspects preview resources and examples
+
+- **WHEN** a maintainer inspects Petclinic preview resources, inline declarations, or the foundation usage example
+- **THEN** preview bodies demonstrate title-free composition
+- **AND** page-level object headers remain present where they identify the current route object
diff --git a/openspec/changes/remove-preview-fragment-titles/specs/generic-vue-web-component-viewer/spec.md b/openspec/changes/remove-preview-fragment-titles/specs/generic-vue-web-component-viewer/spec.md
new file mode 100644
index 00000000000..61fe5c1e421
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/specs/generic-vue-web-component-viewer/spec.md
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Concise Vue Petclinic preview parity
+
+The Vue Petclinic application SHALL match the HTMX reference by retaining each collection row's authoritative title and canonical object link while omitting a repeated `<cw-object-header>` from expanded preview content.
+Its title-free inline previews MUST preserve the same useful details, actions, nested collections, hydrated context, accessible labels, and lifecycle semantics as the HTMX composition.
+
+#### Scenario: Vue Home preview expands
+
+- **WHEN** an Owner or Visit row preview expands on the Vue Home page
+- **THEN** the live preview contains no `<cw-object-header>` and does not repeat the row title
+- **AND** the selected Owner or Visit details remain available
+
+#### Scenario: Vue PetOwner preview expands
+
+- **WHEN** a Pet or Visit row preview expands on the Vue PetOwner page
+- **THEN** the live preview contains no repeated object header
+- **AND** its selected properties, actions, or nested collection remain available under the authoritative row context
+
+#### Scenario: Vue route page renders
+
+- **WHEN** an exact Vue object route renders outside a collection preview
+- **THEN** its page-level `<cw-object-header>` remains present
+- **AND** removing preview titles does not weaken route identity or application navigation
diff --git a/openspec/changes/remove-preview-fragment-titles/tasks.md b/openspec/changes/remove-preview-fragment-titles/tasks.md
new file mode 100644
index 00000000000..5359d31fdb4
--- /dev/null
+++ b/openspec/changes/remove-preview-fragment-titles/tasks.md
@@ -0,0 +1,16 @@
+## 1. HTMX Preview Composition
+
+- [ ] 1.1 Remove `<cw-object-header>` from all Petclinic runtime-type default preview resources while preserving their selected detail members.
+- [ ] 1.2 Remove `<cw-object-header>` from the PetOwner inline Pet preview while preserving editable notes, actions, and nested visits.
+- [ ] 1.3 Update HTMX source and browser tests to verify title-free live previews and retained useful content.
+
+## 2. Vue Preview Parity
+
+- [ ] 2.1 Remove `<cw-object-header>` from Owner and Visit previews on the Vue Home page.
+- [ ] 2.2 Remove `<cw-object-header>` from Pet and Visit previews on the Vue PetOwner page.
+- [ ] 2.3 Update Vue browser assertions and regenerate packaged frontend assets through the established build lifecycle.
+
+## 3. Documentation and Verification
+
+- [ ] 3.1 Update the foundation preview example and Petclinic documentation to recommend concise preview bodies without repeated titles.
+- [ ] 3.2 Run complete foundation, HTMX, Vue, native/Vaadin, Maven packaging, OpenSpec, IDE, and whitespace validation.