feat(TU-45701): add the time_format and time_zone date properties - #169
Draft
trapped wants to merge 3 commits into
Draft
feat(TU-45701): add the time_format and time_zone date properties#169trapped wants to merge 3 commits into
trapped wants to merge 3 commits into
Conversation
The date block can now optionally collect a time of day. A field opts in by setting time_format; omitting the property keeps the field date-only, so there is deliberately no documented default.
The date block defaults structure to MMDDYYYY, not DDMMYYYY. This is a comment only, unrelated to the time work, and safe to drop from this pull request if you would rather it went in on its own.
The Responses API now returns time_zone alongside a date answer. Because the stored date is always a UTC instant, consumers need the zone to show the respondent their own clock. Also states that a time_format property on the field definition, not the presence of time_zone, is what distinguishes a date-only field from one that collects a time of day.
trapped
force-pushed
the
feat/TU-45701_document_time_format_property
branch
from
September 7, 2026 16:21
119b255 to
4822c20
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The date block can now optionally collect a time of day. Two public surfaces change as a result, and
this adds both to
src/typeform-types.ts:time_format?: 'HH:mm' | 'hh:mm a'onProperties.Field, afterseparator. A field opts in bysetting it; when the property is absent the field stays date-only. No
Default:line in theJSDoc — absence of the property is the off state, so documenting a default would imply time is
always collected.
time_zone?: stringon the responseanswersmember, afterdate. An IANA time zone identifier(for example
"America/New_York") captured from the respondent's device at submission time. Thisone is already live — it ships in the Responses API as of today's deploy, so without this change
consumers cannot read a field the API is already returning.
structure's JSDoc claimedDefault: "DDMMYYYY", butthe block's own defaults use
MMDDYYYY(blocks/src/blocks/date/default.json). Comment-only andunrelated to the time work.
Why the
time_zoneJSDoc is carefulThe stored
dateis a true UTC instant, not the respondent's wall clock with aZappended, sotime_zoneis the only thing that can recover the clock the respondent actually saw. Near midnightit recovers the calendar day too.
The JSDoc deliberately does not say that the presence of
time_zoneis what distinguishes adate-only answer from a time-bearing one. Two reasons:
T00:00:00.000Zsuffix, so thedatevalue alonenever distinguishes them; and
time_zoneis omitted when the respondent's device cannot resolve a zone, which can happen on agenuinely time-bearing answer. In practice that essentially never occurs, but it is not
guaranteed, so the JSDoc points readers at the field's
time_formatproperty instead, which is.Motivation and Context
TU-45701 — https://typeform.atlassian.net/browse/TU-45701
Without this, consumers of this client cannot set or read either property without casting, even
though the Forms API accepts one and the Responses API already returns the other.
Testing
npx rollup -c(whatyarn buildruns) — succeeded, so the new types compile and type-check.npx eslint . --max-warnings=0— exit 0.npx jest ./tests/unit(yarn test:unit) — 10 suites / 80 tests passed.yarn install --frozen-lockfile— succeeded withyarn.lockunchanged.Invoked directly rather than through
yarnwhere possible, becauseengines.noderequires >= 24 andthis environment has Node 20. CI runs the supported version.
A standalone
tsc --noEmitreports one pre-existing, unrelated failure innode_modules/@types/istanbul-reports(TS2305, test-tooling types). The repo has notypecheckscript and the real build path compiles the changed file cleanly, so this is noted rather than fixed.
Backward Compatibility
No break. Both properties are optional and additive; no existing type changed shape.
Out of scope, left alone deliberately
The
Typeunion (~line 1331) is missing several block types that already ship. Unrelated to thisticket and worth its own change — flagging it rather than widening this one.
Merge order
No prerequisite. Both added types are declared locally, with no dependency on
@typeform/blocksorany other package that TU-45701 has still to publish, so this is independent of every other pull
request in the effort. Related documentation changes, all independent of one another and of this one:
The
time_formathalf describes a property creators cannot set until the feature flag is on, so thathalf is a release-timing question rather than an ordering one. The
time_zonehalf is already livein production and is the client type catching up.