(causeway) 01/06: docs(openspec): plan clearer preview toggle icon

[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 3757e755802d281a5d3110a04987f0c632565991
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Fri Sep 4 17:52:44 2026 +0100

    docs(openspec): plan clearer preview toggle icon
---
 .../enlarge-preview-toggle-icon/.openspec.yaml     |  2 +
 .../changes/enlarge-preview-toggle-icon/design.md  | 52 ++++++++++++++++++++++
 .../enlarge-preview-toggle-icon/proposal.md        | 27 +++++++++++
 .../specs/domain-web-components/spec.md            | 50 +++++++++++++++++++++
 .../changes/enlarge-preview-toggle-icon/tasks.md   | 17 +++++++
 5 files changed, 148 insertions(+)

diff --git a/openspec/changes/enlarge-preview-toggle-icon/.openspec.yaml b/openspec/changes/enlarge-preview-toggle-icon/.openspec.yaml
new file mode 100644
index 00000000000..1d9aeef992c
--- /dev/null
+++ b/openspec/changes/enlarge-preview-toggle-icon/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-04
diff --git a/openspec/changes/enlarge-preview-toggle-icon/design.md b/openspec/changes/enlarge-preview-toggle-icon/design.md
new file mode 100644
index 00000000000..fe155dda1e1
--- /dev/null
+++ b/openspec/changes/enlarge-preview-toggle-icon/design.md
@@ -0,0 +1,52 @@
+## Context
+
+The framework-neutral collection renderer creates each preview disclosure as a square button containing the text glyph `▸` when collapsed and `▾` when expanded.
+At the rendered size shown in the Petclinic collection, those font-dependent glyphs occupy little visual area and their direction is difficult to distinguish.
+The button's accessible label and `aria-expanded` state already communicate the correct semantics, so the change is limited to making the visible state indicator clearer in every host.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Make the collapsed right-facing direction and expanded downward-facing direction easy to distinguish.
+- Increase the visible icon slightly without increasing the established preview column or button dimensions.
+- Preserve semantic labels, `aria-expanded`, focus, keyboard activation, row alignment, responsive behavior, and preview lifecycle.
+- Keep the implementation framework-neutral and equivalent in HTMX and Vue.
+
+**Non-Goals:**
+
+- Changing collection preview authorization, eligibility, expansion ownership, row identity, hydration, or lifecycle.
+- Changing the preview button's accessible name, dimensions, placement, or public API.
+- Adding a third-party icon dependency or host-specific icon implementation.
+- Redesigning unrelated collection, paging, sorting, or action controls.
+
+## Decisions
+
+### Use one inline chevron geometry and rotate it from semantic state
+
+The disclosure will render an `aria-hidden` inline SVG chevron with a stable view box and stroke rather than a font-dependent triangle character.
+The collapsed state will show the chevron pointing toward the logical forward direction, and the existing `aria-expanded="true"` state will rotate the same geometry downward.
+Using the semantic attribute as the styling selector keeps the visible direction synchronized with the authoritative accessible state.
+
+An alternative was to retain the two Unicode glyphs and only increase `font-size`.
+That would be smaller, but glyph weight, bounds, and baseline remain platform- and font-dependent and can still make the two directions difficult to compare.
+
+### Size the icon independently from the control
+
+The icon will use a shared custom property with a modest default of approximately `1.15rem`, while the preview button retains the established control-height square.
+The SVG will use a clear rounded stroke and no fill so it remains legible in normal, dark, high-contrast, and forced-color presentations through `currentColor`.
+
+An alternative was to enlarge the entire button and preview column.
+That would add row height and whitespace without improving the icon itself and could disturb compact collection alignment.
+
+### Verify shared presentation and unchanged semantics
+
+Foundation tests will verify the SVG hook, size, state-driven rotation, accessible label, and unchanged `aria-expanded` behavior.
+Existing HTMX and Vue Petclinic browser paths will verify collapsed and expanded directions, useful rendered dimensions, focus, and absence of horizontal overflow without adding host-owned behavior.
+
+## Risks / Trade-offs
+
+- [A larger icon could crowd the compact button] → Keep the button unchanged and bound the icon to a modest shared size below the control height.
+- [Rotation could diverge from semantic state] → Select rotation exclusively from the button's existing `aria-expanded` attribute and test both states.
+- [Inline SVG could become an extra accessibility target] → Mark it `aria-hidden="true"` and retain the button's existing state-specific accessible label.
+- [Directional expectations differ in right-to-left layouts] → Use logical inline-direction styling for the collapsed state and verify the current left-to-right Petclinic presentation without changing preview semantics.
diff --git a/openspec/changes/enlarge-preview-toggle-icon/proposal.md b/openspec/changes/enlarge-preview-toggle-icon/proposal.md
new file mode 100644
index 00000000000..0efe9bc59a5
--- /dev/null
+++ b/openspec/changes/enlarge-preview-toggle-icon/proposal.md
@@ -0,0 +1,27 @@
+## Why
+
+The collection row preview disclosure uses a small text glyph whose right-facing and downward-facing states are difficult to distinguish at a glance.
+The control needs a clearer, slightly larger directional icon without changing preview behavior or authority.
+
+## What Changes
+
+- Replace the small preview disclosure text glyph with a larger, consistently sized directional icon.
+- Make collapsed and expanded directions visually distinct while retaining the existing accessible label and `aria-expanded` state.
+- Keep the control dimensions, row alignment, keyboard behavior, focus behavior, and preview lifecycle unchanged.
+- Apply the framework-neutral presentation everywhere the collection preview is used, including HTMX and Vue hosts.
+- Add foundation and browser coverage for both disclosure states and responsive layout.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `domain-web-components`: Require the collection row preview disclosure to present a clearly discernible, appropriately sized collapsed or expanded direction indicator without changing semantic state or interaction behavior.
+
+## Impact
+
+The change affects framework-neutral collection preview markup, shared component styling, foundation tests, HTMX and Vue browser acceptance coverage, and related documentation.
+It adds no dependency, custom element, public attribute, GraphQL behavior, route behavior, or host-specific preview implementation.
diff --git a/openspec/changes/enlarge-preview-toggle-icon/specs/domain-web-components/spec.md b/openspec/changes/enlarge-preview-toggle-icon/specs/domain-web-components/spec.md
new file mode 100644
index 00000000000..62ef4650d43
--- /dev/null
+++ b/openspec/changes/enlarge-preview-toggle-icon/specs/domain-web-components/spec.md
@@ -0,0 +1,50 @@
+## MODIFIED Requirements
+
+### Requirement: Single hydrated row preview lifecycle
+
+An opted-in collection SHALL keep at most one row preview expanded and SHALL provide its live `<cw-preview>` subtree with a dedicated hydrated object context created from the selected authoritative row identity, data, and selection.
+Each preview disclosure MUST present a clearly visible, appropriately sized directional indicator whose collapsed and expanded directions remain synchronized with its authoritative `aria-expanded` state.
+
+#### Scenario: User expands an eligible row
+
+- **WHEN** the user activates a collapsed row's preview disclosure
+- **THEN** the collection creates one live `<cw-preview>` after that row using a fresh clone of its effective template
+- **AND** it assigns the dedicated row context before descendant properties, actions, or collections connect
+- **AND** focus remains on the disclosure while ordinary forward navigation reaches the preview content
+- **AND** the visible indicator changes from the collapsed inline direction to the expanded downward direction without changing the button dimensions
+
+#### Scenario: Preview component requests hydrated data
+
+- **WHEN** a live preview descendant requests a member already selected into the collection row
+- **THEN** the dedicated row context serves the hydrated data without repeating that object read
+
+#### Scenario: Preview component requests additional data
+
+- **WHEN** a live preview descendant requests an authorized member absent from row hydration
+- **THEN** the dedicated row context loads the missing requirement through the established GraphQL client
+- **AND** canonical metadata, hidden, disabled, validation, invocation, and error semantics remain authoritative
+
+#### Scenario: Another row is expanded
+
+- **WHEN** one preview is open and the user activates another eligible row disclosure
+- **THEN** the current preview and its context are retired before the second preview becomes current
+- **AND** no more than one live preview subtree or preview-owned context remains
+
+#### Scenario: User collapses with the disclosure
+
+- **WHEN** the user activates the disclosure for the currently expanded row
+- **THEN** the preview and its context are retired
+- **AND** the disclosure reports the collapsed state
+- **AND** the visible indicator returns to the collapsed inline direction
+
+#### Scenario: User presses Escape inside the preview
+
+- **WHEN** focus is within a live preview and the user presses Escape
+- **THEN** the collection collapses the preview and retires its context
+- **AND** focus returns to the connected disclosure control for that row
+
+#### Scenario: Collection presentation is superseded
+
+- **WHEN** sorting, filtering, paging, reload, parent-context generation, responsive renderer replacement, range supersession, or disconnection changes the collection presentation
+- **THEN** the current preview collapses without preserving expansion state
+- **AND** late resource, context, or renderer work cannot reopen or overwrite a newer row generation
diff --git a/openspec/changes/enlarge-preview-toggle-icon/tasks.md b/openspec/changes/enlarge-preview-toggle-icon/tasks.md
new file mode 100644
index 00000000000..5811fb321f5
--- /dev/null
+++ b/openspec/changes/enlarge-preview-toggle-icon/tasks.md
@@ -0,0 +1,17 @@
+## 1. Shared Preview Disclosure
+
+- [ ] 1.1 Replace the font-dependent preview triangle with one `aria-hidden` inline SVG chevron whose direction is driven by the existing `aria-expanded` state.
+- [ ] 1.2 Add shared component styling for a modestly larger icon, clear current-color stroke, expanded downward rotation, and logical collapsed direction without changing the button or preview-column dimensions.
+- [ ] 1.3 Preserve existing accessible labels, focus restoration, keyboard activation, row identity, and preview lifecycle behavior.
+
+## 2. Foundation Verification
+
+- [ ] 2.1 Extend preview markup and lifecycle tests to verify the SVG hook, hidden decorative semantics, and synchronized collapsed and expanded states.
+- [ ] 2.2 Extend component-style tests to verify icon sizing, stroke presentation, state-driven rotation, logical direction, and unchanged disclosure-control dimensions.
+- [ ] 2.3 Run the complete foundation JavaScript suite under native component presentation.
+
+## 3. Host Acceptance and Documentation
+
+- [ ] 3.1 Extend HTMX and Vue Petclinic browser assertions to verify useful icon dimensions and distinct collapsed and expanded directions without horizontal overflow.
+- [ ] 3.2 Update foundation preview documentation to describe the clearer state indicator without assigning behavior to either host.
+- [ ] 3.3 Run affected Maven, HTMX, Vue, native/Vaadin, OpenSpec, IDE, packaging, and whitespace validation.