docs(edit-content): spec for #37465 Date/Time field width, clearing and picker footer - #37542
adrianjm-dotCMS wants to merge 9 commits into
Conversation
…nd picker footer PR 1 of 2. Spec only — no implementation. Two facts verified against the code rather than taken from the issue shape the priorities: - The timezone renders today only when the field also carries a hint, because the field's footer row is drawn only when there is a hint or a required error. On a Date-and-time field with a timezone and no hint it is never shown at all, so moving it into the picker is a coverage fix, not a relocation. - The current Today action reads the browser's clock, so it can set the wrong calendar day when the server is in another timezone. FR-013 and SC-005 make correcting that explicit. Two open decisions were resolved with the developer before writing and are recorded as Assumptions 2 and 3: the hint returns to the field footer (FR-009), and Today/Now keeps the existing per-type picker-close behaviour (FR-014a). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
|
Claude finished @adrianjm-dotCMS's task in 1m 28s —— View job Spec review —
|
…ooter Scope addition beyond the issue, decided in spec review: the picker footer gains a second button that confirms the selection on Date-and-time and Time-only fields. On those two types the picker no longer writes to the field as the author clicks — it holds a pending selection that reaches the field only on Accept, and dismissing without Accept discards it. Date-only is deliberately excluded: applying the gate there would turn the most common case, setting a plain date, from one interaction into two. It keeps today's behaviour exactly and shows no Accept button. Three consequences were inferred rather than stated and are flagged for a reviewer: Accept styled as the primary action, Accept always enabled, and the gate applying only to picker selections and not to typed input. FR-016a records that #37465's own acceptance criteria now contradict the spec on three points and must be corrected. Like FR-016 it records the obligation only — editing the issue needs developer approval. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…picker footer" This reverts commit e39d460. The Accept button was a scope addition proposed during spec review. The developer decided to build what the issue's acceptance criteria already specify instead, so the spec returns to the single-button footer with the value applied on selection. That also drops FR-016a, which existed only to record that the issue's criteria contradicted the Accept gate. With the gate gone there is no contradiction and #37465 needs no correction. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
FR-016 said "the criterion", following the singular wording of #37465's own body. Checking #37464's description found four passages written around the timezone line under the input, not one: the timezone-versus-hint collision criterion, the criterion for a timezone with no hint, the test asserting the collision case, and the refinement-table row deciding it. FR-009 removes that line, so all four describe an element that will no longer be on the screen. FR-016 now lists each with its location in the issue and requires them to be withdrawn together — dropping only the collision criterion would leave the other three pointing at the same absent element. Still bookkeeping only: it edits a different issue, after merge, and needs developer approval. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…r review Review on PR #37542 found three places where the spec asserted something it then never checked. None is a defect; all three would have let PR 2 be judged against a contract with holes in it. - FR-014a said the picker stays open on Date-and-time and Time-only and closes on Date-only, and no acceptance scenario or success criterion covered it. That is the one place the picker's lifecycle is deliberately non-uniform, so it is also the likeliest thing to regress unnoticed while the footer is rebuilt. Added US3 scenarios 9-11, one per type, and SC-006a. - Assumption 6 pinned "current time" to second precision, but FR-012 and FR-013 said only "the current time" and nothing tested it — an assumption no implementation could be measured against. The precision now lives in FR-012 with SC-005a to check it, and the assumption points at both. - FR-009 read "removed for all three field types", which asks for the removal of an element a Date-only field never rendered. Reworded to name the types that render one today, matching the verified-behaviour table and US2. Both new criteria were checked against the implementation before being written: the open/closed assertions already exist in the child spec, and second precision holds in the unit test and in the verified save/reopen round-trip. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ng labels (#37465) Review on PR #37542 surfaced a real bug: getCurrentServerTime(null) returned UTC clock components reinterpreted as local, while every other timezone-less path in this field (convertServerTimeToUtc, convertUtcToServerTime) treats a missing zone as "use the browser's local clock as-is". The mismatch meant Today/Now displayed one time and stored another, off by the browser's UTC offset — permanently, if the timezone request fails outright rather than merely arriving late. Falls back to the browser's own local clock instead, matching the convention already used elsewhere. No change to the conversion helpers themselves, so FR-017's storage guarantees are untouched. Also: the footer's timezone text now truncates (min-w-0 + truncate, with a title attribute carrying the full label) rather than being able to push the Today/Now button out of the overlay on a very long zone name. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
… after review Second round of review on PR #37542. One finding was a real bug, not a spec gap: - FR-013 didn't say what Today/Now does when the system timezone hasn't loaded yet. Traced it into calendar-field.util.ts: getCurrentServerTime(null) returned UTC clock components read as local time, while every other timezone-less path in this field (convertServerTimeToUtc, convertUtcToServerTime) treats a missing zone as "use local as-is". The mismatch meant a value set with no timezone loaded displayed one time and stored another, off by the browser's UTC offset — permanently, if the timezone request fails outright. FR-013 now states the fallback; SC-006c checks it. Fixed in the implementation on the impl branch, not just documented here. - The "very long timezone labels" edge case had no FR/SC backing it. Added FR-008b and pointed the edge case at it. - The footer action had no keyboard-reachability requirement, unlike the clear control's FR-007a. Added FR-015b, symmetric wording, plus SC-006b. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…#37465 Third round of review on PR #37542. Two findings: FR-013's browser-clock fallback (added last round to fix the display/storage offset bug) meant that if the system timezone genuinely never resolves — its load request has no retry, confirmed in libs/global-store's withSystem — the shortcut can set the browser's day instead of the server's. SC-005 demanded the server's day in 100% of attempts and SC-006c claimed no offset "whether or not the timezone has loaded": neither was satisfiable in that state as worded, so an implementer couldn't tell whether the fallback was required behaviour or a defect. Resolved with the developer, asked directly rather than assumed: keep the fallback. A button that goes permanently dead on a timezone-service failure is worse than one that stays internally consistent (display matches storage) in a case the field already tolerated before this feature — the fallback is exactly the field's pre-#37465 behaviour, narrowed to the one case where the server's zone is genuinely unknown. SC-005 now scopes to "timezone already resolved"; SC-006c now claims only display/storage agreement, not day accuracy; FR-013 states the scoping explicitly; a new Assumption 9 records the decision and why. No code change needed — calendar-field.util.ts already matched this before the spec did. Also fixed a broken in-doc link: [FR-016](#fr-016) doesn't resolve because FR-016 is a bold list item, not a heading. Replaced with plain text, matching the "see FR-008b" convention already used elsewhere in the spec. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…l gaps (#37465) Audited the spec for anything reading as an unresolved decision or a deferred question, per the developer's request — not the review comments, the spec's own language. Two kinds of problem, both closed: Three Assumptions (2, 3, 9) said "confirmed with the developer" / "Decided with the developer". None was missing content — each already stated the full rule and its rationale. The attribution was the problem, not the decision: it reads as an unresolved negotiation even though the paragraph right after it settles the question. Dropped the attribution in all three; the rule now stands on its own like every other Assumption. Two items were genuinely unresolved, caught by external review of PR #37542 rather than by this pass: - SC-005a still claimed the shortcut "matches the server's clock" unconditionally, after SC-005/SC-006c had already been scoped to the resolved-timezone case in the prior commit. Reworded to claim precision only; US3 scenarios 4-7 got the same resolved-timezone caveat. - FR-009 never stated what governs the field footer's visibility once the timezone line is gone. Added FR-009a. Verified against text-field's actual template before writing it, not assumed: the sibling pattern is mutually exclusive (error or hint, never both), while this field's footer stacks them (error first, hint below) — a first draft of FR-009a claimed parity with the siblings and was wrong; caught and corrected before this commit, with the divergence pointed at Out of scope. FR-016's "requires developer approval" was checked and left alone: it gates editing #37464 after merge, correctly scoped as bookkeeping. A sweep for approval/sign-off/pending/TBD/left-to/open-item found nothing else. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Tightens the spec so every requirement states what is built, with no assumptions, deferred decisions or conditional branches left for a reader to resolve. - Drops the Assumptions section. Its substantive content already lived in the FRs; the one rule that didn't (no per-field configuration) becomes FR-020. - Today/Now always resolves through the existing getCurrentServerTime / convertServerTimeToUtc path, as the issue's acceptance criterion requires. The browser-clock fallback is gone from FR-013, and with it SC-006c and the timezone-resolved caveats on SC-005, SC-005a and the US3 scenarios. - Today/Now leaves the picker open on all three field types, the same as selecting a day or time (hideOnDateTimeSelect is false for all three, per #36156). FR-014a previously claimed Date-only closes "as a completed date selection does today", which is not what the field does. - Width is defined as 100% of the column in single- and multi-column layouts; the undefined "narrow viewport" and "supported viewport width" wording is removed from FR-004, SC-002 and US4. - The issue's read-only clause is noted as not valid in FR-006: these fields have no read-only state. - Removes the timezone-unavailable scenario, the late-arrival and long label edge cases, FR-008b, FR-009a and FR-016 with its section, and the "Relationship to #37464" section. - Reframes the timezone change as what it is: a relocation of an existing label. Conversion already worked. User Story 2 drops from P1 to P2; the Today shortcut remains the one timezone-related defect. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 participant
PR 1 of 2 — spec only
This PR carries
spec.mdalone. No implementation, no tests, no product code.Per the Spec-Kit flow,
implementation starts only once another dev approves this spec — approval, not merge:
PR 2 branches off this branch and is opened without waiting for this one to land.
Related to #37465
What the feature is
The three temporal field types in the new Edit Contentlet — Date, Time and
Date and time — are the only fields that look and behave differently from their neighbours.
They sit narrower than their column, they cannot be emptied once a value is set, and the picker
overlay's footer offers a Clear action the author does not need there while hiding the one thing
they do need: which timezone the value is interpreted in.
Four independently shippable user stories: P1 clearing on the field → P1 timezone in the
picker footer → P2 a server-accurate Today / Now → P3 full-column width.
24 functional requirements, 8 success criteria, 8 assumptions.
Two things the code said that the issue did not
Both are load-bearing for the priorities, so they are worth a reviewer's attention:
is drawn only when there is a hint or a required error, so on a Date-and-time field with a
timezone and no hint the timezone is never shown at all. That makes User Story 2 a coverage fix
rather than a relocation, which is why it is P1.
wrong calendar day when the server is in another timezone. FR-013 and SC-005 make correcting
that explicit instead of leaving it as a side effect of rebuilding the footer.
Two decisions the issue left open
Resolved with the developer before writing, rather than carried as
[NEEDS CLARIFICATION].Recorded as Assumptions 2 and 3 so it is visible they were decided, not guessed:
Overlap with #37464
#37464 (Standardize field hint and required-error presentation) is open with no spec and no
branch, so this spec assumes #37465 lands first. FR-009 removes the timezone from the field
footer entirely, which makes #37464's timezone-vs-hint criterion moot. FR-016 records the
obligation to withdraw that criterion from #37464 on merge — bookkeeping across two issues, not
code, and it states in-line that acting on it needs developer approval. If #37464 lands first
instead, FR-008/FR-009 still apply unchanged and only the withdrawal direction reverses.
Explicitly out of scope
Hint and required-error styling and wording (owned by #37464); moving the timezone under the
label; any change to how values are stored or converted between the server timezone and UTC; the
legacy Edit Contentlet screen; the picker's header, day grid and time spinner.
Reviewing this
The spec is the contract PR 2 will be judged against, so the useful questions are about the
requirements, not the code: are FR-001…FR-019 testable as written, is the out-of-scope boundary
where you would draw it, and are Assumptions 2 and 3 the calls you would have made.
checklists/requirements.mdpassed 16/16 on the first validation pass with 0[NEEDS CLARIFICATION]markers; it is gitignored per the repo's spec-folder commit policy, so it is not in this diff.
🤖 Generated with Claude Code