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/09/01 16:17:00 UTC
(causeway) 06/07: docs(openspec): sync parameter temporal range specs
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 7d41cac19681e5f322436f8b2fcaccc0ba6020f5
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Sep 1 17:20:46 2026 +0200
docs(openspec): sync parameter temporal range specs
---
openspec/specs/domain-web-components/spec.md | 54 ++++++++++++++++++++++
.../generic-htmx-web-component-viewer/spec.md | 29 ++++++++++++
.../specs/vaadin-semantic-editor-families/spec.md | 29 ++++++++++++
3 files changed, 112 insertions(+)
diff --git a/openspec/specs/domain-web-components/spec.md b/openspec/specs/domain-web-components/spec.md
index 6552be286f5..70b0886bf01 100644
--- a/openspec/specs/domain-web-components/spec.md
+++ b/openspec/specs/domain-web-components/spec.md
@@ -2392,3 +2392,57 @@ Valid bounds MUST constrain both the presented editor and Causeway-owned propert
#### Scenario: Property datatype is not a supported local temporal
- **WHEN** `min` or `max` appears on a non-temporal, offset, zoned, legacy, read-only, or unsupported temporal property presentation
- **THEN** the attributes do not change value rendering, editor selection, parsing, validation, or GraphQL behavior
+
+### Requirement: Declarative local-temporal action-parameter ranges
+An optional direct-child `<cw-parameter>` declaration SHALL accept `min` and `max` attributes and properties for authoritative `LocalDate`, `LocalTime`, and `LocalDateTime` action parameters.
+Valid bounds MUST constrain the presented editor and Causeway-owned prompt validation without changing authoritative parameter existence, order, type, defaults, choices, required state, visibility, disabled state, canonical validation, confirmation, or invocation.
+
+#### Scenario: Absolute local-date parameter interval is authored
+- **WHEN** a declared authoritative `LocalDate` parameter has valid ascending ISO `min` and `max` bounds
+- **THEN** its native or qualified editor exposes the closed date interval
+- **AND** values equal to either boundary remain admissible
+
+#### Scenario: Office-hour parameter interval is authored
+- **WHEN** a declared authoritative `LocalTime` parameter has `min="08:00"` and `max="17:00"`
+- **THEN** its editor exposes that closed time interval while retaining the supported quarter-hour picker choices
+- **AND** accepted pending seconds, fractional seconds, and off-quarter-hour minutes remain unchanged until explicitly edited
+
+#### Scenario: Local date-time parameter interval is authored
+- **WHEN** a declared authoritative `LocalDateTime` parameter has compatible absolute ISO bounds
+- **THEN** its editor receives matching local date-time bounds without UTC conversion
+- **AND** comparison uses local calendar and clock parts
+
+#### Scenario: Relative parameter bound begins a prompt
+- **WHEN** `today` or `tomorrow` is declared for a `LocalDate`, or `now` is declared for a `LocalDateTime`, and the action prompt begins
+- **THEN** the token resolves once from the browser's current local calendar or clock after the authoritative datatype is known
+- **AND** the resolved boundary remains stable for that prompt generation and resolves again for a later opening
+
+#### Scenario: Pending parameter lies outside its range
+- **WHEN** a well-formed pending local-temporal parameter value compares outside its resolved closed interval
+- **THEN** the prompt retains the pending value and presents a field-specific correction naming the violated boundary
+- **AND** no GraphQL preparation, action validation, confirmation, or invocation request is issued for that attempt
+
+#### Scenario: Pending parameter is corrected
+- **WHEN** the user corrects the pending value into the resolved interval
+- **THEN** the local range reason clears and canonical preparation and action validation resume
+- **AND** canonical domain validation can still reject the value independently
+
+#### Scenario: Prompt submission finds an out-of-range value
+- **WHEN** submission occurs before a bounded parameter has committed a valid in-range value
+- **THEN** submission fails locally and focus moves through the existing first-invalid-control lifecycle
+- **AND** the prompt remains open with all pending values available for correction or cancellation
+
+#### Scenario: Authored parameter interval is unusable
+- **WHEN** either bound is blank, malformed, incompatible with the authoritative datatype, or resolves below the minimum
+- **THEN** the entire authored interval is ignored and the canonical parameter editor remains usable
+- **AND** the rendered parameter exposes a deterministic invalid-range diagnostic hook without fabricating a bound
+
+#### Scenario: Parameter is undeclared or inapplicable
+- **WHEN** no matching declaration exists, or `min` or `max` is declared for a non-local, offset, zoned, legacy, reference, or unsupported parameter
+- **THEN** editor selection, parsing, validation, defaults, choices, and GraphQL behavior remain unchanged
+- **AND** declaration data cannot create, remove, or reorder an authoritative parameter
+
+#### Scenario: Prompt is cancelled or reopened
+- **WHEN** a bounded prompt is cancelled and later reopened
+- **THEN** cancellation uses the existing focus-restoration lifecycle without invoking the action
+- **AND** the new prompt resolves a fresh immutable range from its own start time
diff --git a/openspec/specs/generic-htmx-web-component-viewer/spec.md b/openspec/specs/generic-htmx-web-component-viewer/spec.md
index 433f36c334b..f8d67174508 100644
--- a/openspec/specs/generic-htmx-web-component-viewer/spec.md
+++ b/openspec/specs/generic-htmx-web-component-viewer/spec.md
@@ -1024,3 +1024,32 @@ The Petclinic owner page SHALL demonstrate declarative temporal range constraint
- **WHEN** Petclinic runs with Vaadin-default and explicit native field policy
- **THEN** the same authored `min` and `max` declaration constrains both editors
- **AND** no raw Vaadin element or API is required in Petclinic markup
+
+### Requirement: Petclinic bounded visit parameter qualification
+The Petclinic owner page SHALL demonstrate declarative action-parameter ranges by booking visits with a future `LocalDate` and an inclusive office-hours `LocalTime` through direct-child `<cw-parameter>` declarations.
+The domain action MUST combine accepted date and time values into the existing authoritative visit date-time and retain canonical validation for both constraints.
+
+#### Scenario: Book Visit prompt opens
+- **WHEN** browser acceptance opens `bookVisit`
+- **THEN** the date editor exposes the resolved `tomorrow` minimum and the time editor exposes `08:00` and `17:00` bounds
+- **AND** defaults, parameter order, labels, prompt style, picker accessibility, and cancellation remain authoritative or presentation-driven as before
+
+#### Scenario: Non-future visit date is attempted
+- **WHEN** the user enters a date before the resolved future-date minimum
+- **THEN** the prompt retains the date and presents a local minimum reason
+- **AND** no `bookVisit` GraphQL preparation, validation, or mutation request occurs for the rejected attempt
+
+#### Scenario: Time outside office hours is attempted
+- **WHEN** the user enters a well-formed time before `08:00` or after `17:00`
+- **THEN** the prompt retains the time and presents the matching local boundary reason
+- **AND** no `bookVisit` GraphQL preparation, validation, or mutation request occurs for the rejected attempt
+
+#### Scenario: Visit date and time are corrected
+- **WHEN** both pending values lie within their declared ranges
+- **THEN** canonical action validation and one `bookVisit` mutation proceed
+- **AND** the refreshed visit collection exposes the combined authoritative local date-time
+
+#### Scenario: Native and Vaadin policies are exercised
+- **WHEN** Petclinic runs under the default Vaadin and explicit native component-toolkit policies
+- **THEN** both date and time controls receive equivalent bounds and local request gating
+- **AND** Petclinic markup contains only public Causeway elements and attributes
diff --git a/openspec/specs/vaadin-semantic-editor-families/spec.md b/openspec/specs/vaadin-semantic-editor-families/spec.md
index 378f2f65779..0cd6a0d9454 100644
--- a/openspec/specs/vaadin-semantic-editor-families/spec.md
+++ b/openspec/specs/vaadin-semantic-editor-families/spec.md
@@ -306,3 +306,32 @@ Causeway SHALL remain authoritative for interval normalization, local validation
- **WHEN** a qualified temporal field is used only for read-only presentation
- **THEN** authored property bounds are not applied to that internal control
- **AND** accepted authoritative precision remains visible and unchanged
+
+### Requirement: Qualified action-parameter temporal range propagation
+The qualified Vaadin local-temporal adapter SHALL consume Causeway-resolved `min` and `max` values from action-parameter editor contexts for editable date-picker, time-picker, and date-time-picker controls.
+Causeway SHALL remain authoritative for declaration matching, interval normalization, local request gating, pending values, canonical validation, and invocation.
+
+#### Scenario: Parameter date picker receives bounds
+- **WHEN** an eligible `LocalDate` action parameter carries a valid resolved interval
+- **THEN** the internal date picker receives matching ISO bounds before its pending or default value
+- **AND** calendar choices outside the interval follow the toolkit's supported disabled-range behavior
+
+#### Scenario: Parameter time picker receives office hours
+- **WHEN** an eligible `LocalTime` action parameter carries `08:00` and `17:00` bounds
+- **THEN** the internal time picker receives both bounds and retains the established 15-minute dropdown step
+- **AND** its labelled clock trigger, synchronous keyboard activation, clear control, and focus behavior remain unchanged
+
+#### Scenario: Parameter date-time picker receives bounds
+- **WHEN** an eligible `LocalDateTime` action parameter carries a valid resolved interval
+- **THEN** the internal date-time picker receives matching local ISO bounds without timezone conversion
+- **AND** its composed date and time controls retain accessible names and triggers
+
+#### Scenario: Parameter range is absent or invalid
+- **WHEN** the action-parameter editor context carries no valid resolved interval
+- **THEN** the internal Vaadin control receives no minimum or maximum
+- **AND** qualification, native fallback, default value, required state, disabled state, and prompt lifecycle remain unchanged
+
+#### Scenario: Bounded parameter prompt is cancelled
+- **WHEN** a qualified bounded parameter editor is cancelled without invocation
+- **THEN** its overlay, clear control, pending state, and focus are disposed through the existing prompt lifecycle
+- **AND** reopening installs controls with newly resolved bounds and no stale adapter state