You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2026/08/29 14:24:21 UTC
(causeway) 03/06: docs(openspec): archive collection headings
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 88203c35bf6a3532eb1a370e60f62b0071bd131b
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Aug 29 15:57:21 2026 +0200
docs(openspec): archive collection headings
---
.../.openspec.yaml | 0
.../design.md | 0
.../proposal.md | 0
.../specs/domain-web-components/spec.md | 0
.../generic-htmx-web-component-viewer/spec.md | 0
.../specs/graphql-web-component-context/spec.md | 0
.../tasks.md | 0
openspec/specs/domain-web-components/spec.md | 41 ++++++++++++++++++++++
.../generic-htmx-web-component-viewer/spec.md | 26 ++++++++++++++
.../specs/graphql-web-component-context/spec.md | 18 ++++++++++
10 files changed, 85 insertions(+)
diff --git a/openspec/changes/enhance-collection-headings/.openspec.yaml b/openspec/changes/archive/2026-08-29-enhance-collection-headings/.openspec.yaml
similarity index 100%
rename from openspec/changes/enhance-collection-headings/.openspec.yaml
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/.openspec.yaml
diff --git a/openspec/changes/enhance-collection-headings/design.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/design.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/design.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/design.md
diff --git a/openspec/changes/enhance-collection-headings/proposal.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/proposal.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/proposal.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/proposal.md
diff --git a/openspec/changes/enhance-collection-headings/specs/domain-web-components/spec.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/domain-web-components/spec.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/specs/domain-web-components/spec.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/domain-web-components/spec.md
diff --git a/openspec/changes/enhance-collection-headings/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/generic-htmx-web-component-viewer/spec.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/specs/generic-htmx-web-component-viewer/spec.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/generic-htmx-web-component-viewer/spec.md
diff --git a/openspec/changes/enhance-collection-headings/specs/graphql-web-component-context/spec.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/graphql-web-component-context/spec.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/specs/graphql-web-component-context/spec.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/specs/graphql-web-component-context/spec.md
diff --git a/openspec/changes/enhance-collection-headings/tasks.md b/openspec/changes/archive/2026-08-29-enhance-collection-headings/tasks.md
similarity index 100%
rename from openspec/changes/enhance-collection-headings/tasks.md
rename to openspec/changes/archive/2026-08-29-enhance-collection-headings/tasks.md
diff --git a/openspec/specs/domain-web-components/spec.md b/openspec/specs/domain-web-components/spec.md
index 10ffc1e0eb5..49110278aac 100644
--- a/openspec/specs/domain-web-components/spec.md
+++ b/openspec/specs/domain-web-components/spec.md
@@ -1644,3 +1644,44 @@ The component registry, ECMAScript exports, semantic element-name constants, sty
#### Scenario: Application uses plain HTML
- **WHEN** an application imports the standard foundation entry module and writes `<cw-breadcrumbs>` beneath an object context
- **THEN** the element is registered and operates without a frontend framework or direct GraphQL document construction
+
+### Requirement: Semantic collection headings
+The `<cw-collection>` component SHALL render one semantic collection heading from an explicit HTML name, canonical member metadata, or a safe member-id fallback.
+It SHALL render a distinct available description directly below that heading in subdued, smaller text and associate both texts with every collection presentation state.
+
+#### Scenario: HTML supplies both overrides
+- **WHEN** a collection declares non-blank `named` and `described-as` attributes
+- **THEN** those values are the rendered collection name and description
+- **AND** they override canonical friendly-name and description metadata
+
+#### Scenario: Canonical metadata supplies heading text
+- **WHEN** no applicable HTML override exists and the collection response supplies canonical `metadata.friendlyName` or `metadata.description`
+- **THEN** each available value is used independently
+- **AND** a missing value falls back to a humanized member id for the name or no description for the description
+
+#### Scenario: Legacy label remains present
+- **WHEN** a collection declares the existing `label` attribute without `named`
+- **THEN** the label remains the effective name for backward compatibility
+- **AND** `named` takes precedence when both are non-blank
+
+#### Scenario: Description duplicates resolved name
+- **WHEN** the candidate description equals the resolved name after trimming and case-insensitive comparison
+- **THEN** no duplicate description is rendered or referenced
+
+#### Scenario: Heading attributes change
+- **WHEN** `named`, `described-as`, `label`, or the member id changes while the component is connected
+- **THEN** the current collection shell rerenders with the newly resolved accessible heading
+- **AND** collection data is not independently reloaded solely for the text change
+
+### Requirement: Quiet read-only collection presentation
+Collection wrappers SHALL remain read-only and authorization-aware without rendering their disabled or unmodifiable boolean or reason as visible explanatory text, a label, or a tooltip.
+
+#### Scenario: Mixed-in collection is unmodifiable
+- **WHEN** a readable mixed-in collection reports a disabled reason such as “Cannot edit a mixed-in collection”
+- **THEN** its rows, heading, description, paging, and applicable associated actions remain available
+- **AND** the collection-level reason is not rendered as text or tooltip
+
+#### Scenario: Member or associated action is disabled
+- **WHEN** an individual row member or associated action has its own disabled state and reason
+- **THEN** that control retains its established semantic state and explanation
+- **AND** collection-level suppression does not broaden authorization or enable mutation
diff --git a/openspec/specs/generic-htmx-web-component-viewer/spec.md b/openspec/specs/generic-htmx-web-component-viewer/spec.md
index 4a39c5489d8..8a9d89ed0b4 100644
--- a/openspec/specs/generic-htmx-web-component-viewer/spec.md
+++ b/openspec/specs/generic-htmx-web-component-viewer/spec.md
@@ -653,3 +653,29 @@ The application MUST NOT require a shared foundation, HTMX viewer, or web-compon
- **WHEN** the same application is rendered below its responsive breakpoints
- **THEN** existing gutters, stacking, contained collection presentation, and no-overflow behavior remain effective
- **AND** the full-width override does not introduce horizontal document overflow
+
+### Requirement: Petclinic collection heading demonstrations
+The Petclinic HTMX application SHALL selectively demonstrate canonical collection descriptions, HTML-authored collection names, and HTML-authored collection description overrides without requiring application-specific component code.
+
+#### Scenario: Domain facet supplies a description
+- **WHEN** a Petclinic collection annotated with `@CollectionLayout(describedAs)` is rendered without an HTML description override
+- **THEN** its canonical description appears below the effective collection name
+- **AND** collections without a description remain free of placeholder prose
+
+#### Scenario: HTML supplies collection heading overrides
+- **WHEN** a Petclinic resource page declares `named` or `described-as` on selected `<cw-collection>` elements
+- **THEN** those explicit values appear for those collections only
+- **AND** the same component continues using canonical metadata or fallbacks for other collections
+
+#### Scenario: Petclinic owner visits are rendered
+- **WHEN** the mixed-in owner visits collection loads
+- **THEN** its selected name and description are visible and accessible
+- **AND** “Cannot edit a mixed-in collection” or an equivalent collection-level tooltip is absent
+
+### Requirement: Petclinic collection heading regression coverage
+Petclinic integration and browser acceptance SHALL verify canonical and HTML-authored collection heading combinations, quiet read-only collection presentation, and unaffected collection navigation and actions.
+
+#### Scenario: Petclinic heading combinations are exercised
+- **WHEN** integration and browser tests inspect selected home and owner collections
+- **THEN** names and descriptions follow documented precedence and selective application
+- **AND** existing rows, links, paging, responsive behavior, add/remove/book actions, and error monitoring remain valid
diff --git a/openspec/specs/graphql-web-component-context/spec.md b/openspec/specs/graphql-web-component-context/spec.md
index b8d35e63194..f76b094a934 100644
--- a/openspec/specs/graphql-web-component-context/spec.md
+++ b/openspec/specs/graphql-web-component-context/spec.md
@@ -233,3 +233,21 @@ The object context SHALL associate a GraphQL error on navigable breadcrumb metad
- **WHEN** the object response contains current metadata and member data plus an error at the breadcrumb field path
- **THEN** the breadcrumbs consumer receives a partial-error state
- **AND** successful header, property, action, and collection consumers retain their normal state
+
+### Requirement: Targeted collection heading metadata
+A semantic collection requirement SHALL select supported canonical `friendlyName` and `description` fields from the collection wrapper's existing metadata object alongside collection visibility and usability state.
+
+#### Scenario: Collection metadata fields are supported
+- **WHEN** targeted introspection finds `metadata.friendlyName` or `metadata.description` on a requested collection wrapper
+- **THEN** the object-context selection includes only the supported heading metadata fields
+- **AND** accepted response metadata is delivered with the current collection requirement state
+
+#### Scenario: Collection metadata is unavailable or partially erroneous
+- **WHEN** the wrapper lacks either heading field or GraphQL reports a nullable field-local error
+- **THEN** the remaining supported collection state stays usable
+- **AND** the component can apply explicit HTML overrides or safe fallbacks without a complete-schema read
+
+#### Scenario: Collection heading attribute changes
+- **WHEN** an HTML-only name or description override changes after metadata has loaded
+- **THEN** the component reuses the current requirement state
+- **AND** no extra GraphQL request is issued solely for presentation text