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/31 19:24:46 UTC
(causeway) 03/03: docs(openspec): archive time and multiline editor usability
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 c4fc92770d44299e49c7863f86799ff86721ea3e
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Aug 31 18:57:08 2026 +0200
docs(openspec): archive time and multiline editor usability
---
.../.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/vaadin-semantic-editor-families/spec.md | 0
.../tasks.md | 0
openspec/specs/domain-web-components/spec.md | 32 +++++++++
.../generic-htmx-web-component-viewer/spec.md | 17 +++++
.../specs/vaadin-semantic-editor-families/spec.md | 76 ++++++++++++++++++++++
10 files changed, 125 insertions(+)
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/.openspec.yaml b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/.openspec.yaml
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/.openspec.yaml
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/.openspec.yaml
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/design.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/design.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/design.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/design.md
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/proposal.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/proposal.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/proposal.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/proposal.md
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/specs/domain-web-components/spec.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/domain-web-components/spec.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/specs/domain-web-components/spec.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/domain-web-components/spec.md
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/specs/generic-htmx-web-component-viewer/spec.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/generic-htmx-web-component-viewer/spec.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/specs/generic-htmx-web-component-viewer/spec.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/generic-htmx-web-component-viewer/spec.md
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/specs/vaadin-semantic-editor-families/spec.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/vaadin-semantic-editor-families/spec.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/specs/vaadin-semantic-editor-families/spec.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/specs/vaadin-semantic-editor-families/spec.md
diff --git a/openspec/changes/improve-time-and-multiline-editor-usability/tasks.md b/openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/tasks.md
similarity index 100%
rename from openspec/changes/improve-time-and-multiline-editor-usability/tasks.md
rename to openspec/changes/archive/2026-08-31-improve-time-and-multiline-editor-usability/tasks.md
diff --git a/openspec/specs/domain-web-components/spec.md b/openspec/specs/domain-web-components/spec.md
index e4404a09d85..8a74f433483 100644
--- a/openspec/specs/domain-web-components/spec.md
+++ b/openspec/specs/domain-web-components/spec.md
@@ -2251,3 +2251,35 @@ A modal action prompt whose first applicable parameter is an asynchronously upgr
- **WHEN** the user presses Escape while the reference editor's dropdown is open
- **THEN** the editor may consume that press to close its dropdown
- **AND** a subsequent Escape from the closed editor cancels the prompt
+
+### Requirement: Shared minute-precision temporal entry
+Editable `<cw-property>` and `<cw-parameter>` local-time and local-date-time values SHALL use the same qualified one-minute entry precision when rendered through the Vaadin field adapter.
+Causeway codecs and interaction owners MUST remain authoritative for lexical parsing, validation, pending state, cancellation, property mutation, and action invocation.
+
+#### Scenario: Property time is entered
+- **WHEN** an editable local-time or local-date-time property uses the qualified toolkit adapter
+- **THEN** its time entry and picker choices are limited to minute precision
+- **AND** successful save submits the minute-aligned local lexical value through the established property interaction
+
+#### Scenario: Parameter time is entered
+- **WHEN** a local-time or local-date-time action parameter uses the qualified toolkit adapter
+- **THEN** its time entry and picker choices are limited to minute precision
+- **AND** successful invocation submits the minute-aligned local lexical value through the established parameter negotiation path
+
+#### Scenario: Temporal edit is cancelled
+- **WHEN** a property or parameter temporal editor is cancelled
+- **THEN** its authoritative or prepared value remains unchanged
+- **AND** no minute normalization is persisted or invoked solely because the editor was displayed
+
+### Requirement: Semantic time-picker affordance
+Qualified property and action-parameter time editors SHALL provide equivalent pointer and keyboard access to their visible clock affordance without exposing Vaadin APIs in application markup.
+
+#### Scenario: Property clock trigger is activated
+- **WHEN** a user reaches or clicks an editable property's clock trigger
+- **THEN** the time picker opens with an accessible name derived from the property label
+- **AND** existing property focus, validation, save, and cancel behavior remains owned by `<cw-property>`
+
+#### Scenario: Parameter clock trigger is activated
+- **WHEN** a user reaches or clicks an action parameter's clock trigger
+- **THEN** the time picker opens with an accessible name derived from the effective parameter label
+- **AND** existing prompt focus containment, validation, submission, and cancellation remain controller-owned
diff --git a/openspec/specs/generic-htmx-web-component-viewer/spec.md b/openspec/specs/generic-htmx-web-component-viewer/spec.md
index a88483e6120..3bc40bb7d4d 100644
--- a/openspec/specs/generic-htmx-web-component-viewer/spec.md
+++ b/openspec/specs/generic-htmx-web-component-viewer/spec.md
@@ -925,3 +925,20 @@ Petclinic browser verification SHALL exercise Escape cancellation for the `remov
- **WHEN** the same action is activated after Escape cancellation
- **THEN** its authoritative parameter values and choices are prepared normally
- **AND** the earlier cancellation has not invoked or corrupted the action lifecycle
+
+### Requirement: Petclinic time and multiline editor usability qualification
+The Petclinic browser profile SHALL qualify minute-resolution date-time parameter entry, keyboard and pointer clock-trigger operation, and single-ring multiline parameter focus through the public HTMX viewer.
+
+#### Scenario: Visit date-time parameter is operated
+- **WHEN** the browser opens the demonstrated visit-booking action and reaches its date-time parameter
+- **THEN** the time field displays and selects at minute precision
+- **AND** keyboard and pointer activation of its labelled clock trigger opens the time overlay without invoking the action
+
+#### Scenario: Multiline parameter receives keyboard focus
+- **WHEN** the browser focuses the demonstrated multiline reason parameter
+- **THEN** exactly one visible focus ring identifies the editor
+- **AND** the parameter remains editable, described, and submittable through its existing action prompt
+
+#### Scenario: Browser qualification remains clean
+- **WHEN** the time and multiline journeys complete or cancel
+- **THEN** no unexpected mutation, action invocation, focus loss, console error, page error, CSP violation, external request, overlay leak, or horizontal overflow occurs
diff --git a/openspec/specs/vaadin-semantic-editor-families/spec.md b/openspec/specs/vaadin-semantic-editor-families/spec.md
index 62329a04bd2..3fb2e09229a 100644
--- a/openspec/specs/vaadin-semantic-editor-families/spec.md
+++ b/openspec/specs/vaadin-semantic-editor-families/spec.md
@@ -163,3 +163,79 @@ Keyboard use of the trigger MUST preserve Causeway-owned pending value, validati
- **WHEN** the pinned Vaadin date picker no longer exposes the qualified internal calendar affordance
- **THEN** browser qualification fails with the missing keyboard contract identified
- **AND** applications are not required to address Vaadin shadow-DOM structure directly
+
+### Requirement: Minute-resolution local-time entry
+Each editable qualified Vaadin `LocalTime` or `LocalDateTime` control SHALL present and accept user-entered time at one-minute resolution.
+The adapter MUST use the toolkit's supported step contract and MUST NOT introduce a second temporal parser or mutate authoritative state merely by entering edit mode.
+
+#### Scenario: User edits a local time
+- **WHEN** a property or action parameter opens an editable qualified `LocalTime` control
+- **THEN** the visible entry omits seconds and fractional seconds
+- **AND** a newly selected or typed valid value is aligned to the minute before the existing codec validates it
+
+#### Scenario: User edits a local date-time
+- **WHEN** a property or action parameter opens an editable qualified `LocalDateTime` control
+- **THEN** its integrated time field uses the same one-minute resolution
+- **AND** the local date, local time, and absence of browser timezone conversion remain authoritative
+
+#### Scenario: User cancels a precise existing value
+- **WHEN** an authoritative value contains accepted seconds or fractional seconds and the user cancels without committing a changed minute value
+- **THEN** the authoritative value remains unchanged
+- **AND** no rounded or truncated value is submitted
+
+#### Scenario: Value is read-only or uses native fallback
+- **WHEN** the value is presented read-only or the Vaadin family is ineligible or disabled
+- **THEN** its established precision and native semantic behavior remain unchanged
+
+### Requirement: Accessible local-time clock trigger
+Each editable qualified Vaadin time picker SHALL expose its clock trigger as a semantic-field-labelled button in the normal sequential keyboard focus order.
+This contract SHALL apply to standalone time pickers and the time child of date-time pickers.
+Keyboard or pointer use of the trigger MUST preserve Causeway-owned pending value, validation, commit, cancellation, and focus semantics.
+
+#### Scenario: Keyboard user reaches the clock trigger
+- **WHEN** focus is in an editable qualified time input and the user presses Tab
+- **THEN** focus moves to the associated clock trigger
+- **AND** the trigger's accessible name identifies the time picker and semantic field
+
+#### Scenario: Keyboard user opens the time picker
+- **WHEN** the focused clock trigger receives Enter or Space
+- **THEN** the existing Vaadin time overlay opens for minute-resolution selection
+- **AND** no property commit, action-parameter commit, submission, or cancellation occurs merely because focus moved to or activated the trigger
+
+#### Scenario: Pointer user opens the time picker
+- **WHEN** a pointer user activates the visible clock trigger
+- **THEN** the existing Vaadin time overlay opens
+- **AND** the trigger is not blocked by adapter styling or hidden accessibility state
+
+#### Scenario: Composite date-time order
+- **WHEN** a keyboard user traverses an editable qualified date-time picker
+- **THEN** the date input, calendar trigger, time input, and clock trigger are reachable in meaningful order
+- **AND** reverse Tab traversal returns through the same associated controls
+
+#### Scenario: Time control is not operable
+- **WHEN** a qualified time control is read-only or disabled
+- **THEN** it does not expose an operable clock trigger in the Tab sequence
+- **AND** its existing read-only or disabled semantic state remains authoritative
+
+#### Scenario: Pinned toolkit structure drifts
+- **WHEN** the pinned Vaadin time picker no longer exposes the qualified internal clock affordance
+- **THEN** browser qualification fails with the missing keyboard and pointer contract identified
+- **AND** applications are not required to address Vaadin shadow-DOM structure directly
+
+### Requirement: Single-ring multiline toolkit focus
+An editable qualified Vaadin multiline control SHALL display one clear focus indicator rather than combining the application host outline with the toolkit's internal input focus ring.
+
+#### Scenario: Multiline property receives focus
+- **WHEN** keyboard focus enters a qualified Vaadin multiline property editor
+- **THEN** the toolkit focus ring remains visible
+- **AND** no second application-level outline surrounds the complete toolkit host
+
+#### Scenario: Multiline action parameter receives focus
+- **WHEN** keyboard focus enters a qualified Vaadin multiline action parameter
+- **THEN** it uses the same single-ring presentation as the property editor
+- **AND** its clear affordance, resize behavior, validation, and accessible description remain unchanged
+
+#### Scenario: Native textarea receives focus
+- **WHEN** native toolkit fallback renders a multiline editor
+- **THEN** the application focus-visible outline remains available
+- **AND** focus indication is not suppressed by the Vaadin-specific rule