Skip to content

feat(TU-45701): add the time_format and time_zone date properties - #169

Draft
trapped wants to merge 3 commits into
mainfrom
feat/TU-45701_document_time_format_property
Draft

feat(TU-45701): add the time_format and time_zone date properties#169
trapped wants to merge 3 commits into
mainfrom
feat/TU-45701_document_time_format_property

Conversation

@trapped

@trapped trapped commented Aug 17, 2026

Copy link
Copy Markdown
Member

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' on Properties.Field, after separator. A field opts in by
    setting it; when the property is absent the field stays date-only. No Default: line in the
    JSDoc — absence of the property is the off state, so documenting a default would imply time is
    always collected.
  • time_zone?: string on the response answers member, after date. An IANA time zone identifier
    (for example "America/New_York") captured from the respondent's device at submission time. This
    one 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.
  • Second commit (independent, safe to drop): structure's JSDoc claimed Default: "DDMMYYYY", but
    the block's own defaults use MMDDYYYY (blocks/src/blocks/date/default.json). Comment-only and
    unrelated to the time work.

Why the time_zone JSDoc is careful

The stored date is a true UTC instant, not the respondent's wall clock with a Z appended, so
time_zone is the only thing that can recover the clock the respondent actually saw. Near midnight
it recovers the calendar day too.

The JSDoc deliberately does not say that the presence of time_zone is what distinguishes a
date-only answer from a time-bearing one. Two reasons:

  1. a date-only answer also serializes with a T00:00:00.000Z suffix, so the date value alone
    never distinguishes them; and
  2. time_zone is omitted when the respondent's device cannot resolve a zone, which can happen on a
    genuinely time-bearing answer. In practice that essentially never occurs, but it is not
    guaranteed, so the JSDoc points readers at the field's time_format property 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 (what yarn build runs) — 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 with yarn.lock unchanged.

Invoked directly rather than through yarn where possible, because engines.node requires >= 24 and
this environment has Node 20. CI runs the supported version.

A standalone tsc --noEmit reports one pre-existing, unrelated failure in
node_modules/@types/istanbul-reports (TS2305, test-tooling types). The repo has no typecheck
script 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 Type union (~line 1331) is missing several block types that already ship. Unrelated to this
ticket 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/blocks or
any 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_format half describes a property creators cannot set until the feature flag is on, so that
half is a release-timing question rather than an ordering one. The time_zone half is already live
in production and is the client type catching up.

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
trapped force-pushed the feat/TU-45701_document_time_format_property branch from 119b255 to 4822c20 Compare September 7, 2026 16:21
@trapped trapped changed the title feat(TU-45701): add the time_format field property feat(TU-45701): add the time_format and time_zone date properties Sep 7, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant