formkit / tempo

📆 Parse, format, manipulate, and internationalize dates and times in JavaScript and TypeScript.

Documentation website

FormKit

Vue 3 form development. 10x faster.

FormKit is a form-authoring framework for Vue developers that makes building high quality production-ready forms 10x faster. It is easy-to-learn and ships with production-ready scaffolding like inputs, forms, submission and error handling, and validation rules. To learn more check out the documentation website at: formkit.com.

Sponsors

FormKit — which supports its whole feature set for native HTML inputs (like select, checkbox, and textarea) — is and will always be an MIT-licensed open source project. Please consider sponsoring FormKit so we can sustainably and continually improve it! There are a variety of sponsor tiers and benefits for each sponsor.

💎 Platinum sponsors

🥇 Gold sponsors

🥈 Silver sponsors

🥉 Bronze sponsors

Backers

uscreen, gfenn08, Ryan E, João Bondim

Key features
☝️ Comprehensive package FormKit is an all-in-one form-authoring framework with input scaffolding (labels, help text, etc.), validation, form UI & styling, error handling, generation, a11y, i18n, and more!	😎 Developer happiness Forms are everywhere, yet surprisingly tedious to author — well, not anymore. FormKit provides a powerful and flexible API to developers that makes complex form creation a breeze.
🎯 Validation built in Ridiculously easy validation out-of-the-box to handle 95% of use-cases. Help text, validation rules, and validation messages are simple props. Need more? You can add custom validation rules too.	⚡️ Blazing-fast Performance FormKit can handle the most demanding forms — wizards, multi-step, deeply nested repeating groups, and more.
🔌 Plugin system Extend FormKit's functionality or reuse custom inputs, validation rules and messages across projects by tapping into the plugin system. Make your plugin open source to share with others!	✨ Generate forms Generate an entire form from a JSON-compatible schema. Schema allows you to render complex forms from JSON with conditional rendering, logic, dynamic data, groups, wrappers, HTML elements, and custom components.
🎨 Robust Theming FormKit works easily alongside your favorite UI frameworks like Bootstrap and utility-class tools like Tailwind. With numerous ways to modify classes and DOM structure, integrating FormKit plays nicely with any frontend.	🌐 Internationalization FormKit is made for all! Thanks to the FormKit community, FormKit ships with support for many languages. Don't see your language? Contribute one with our locale builder.

Contributing

Thank you for your willingness to contribute to this free and open source project! When contributing, consider first discussing your desired change with the core team via GitHub issues, Discord, or other method.

Contributors

This project exists thanks to all the people who volunteer their time to contribute!

License

MIT

Copyright (c) 2021-present, FormKit, Inc.

tempo's Issues

various mobile ui issues (ios)

very cool project and beautiful website 👏

found a few issues on mobile safari (ios) and thought i'd mention tho:

search not jumping to results:

trim.10277AEE-FDEB-4104-87E9-C6302853D0FF.MOV

overflow:

text mangling (multiple places):

background clipping above bottom:

Feature request: `differenceInMilliseconds` / `differenceInSeconds` / `differenceInMinutes` / etc.

Hi and thanks for the great library.

One thing I'm missing is the ability to get the difference between a pair of dates in different units.

Similar function in other libraries:

• Day.js
• date-fns
• Moment.js

It would be great to have these functions in Tempo, thanks!

Feature request: weekNumber

Thanks for this library its a delight to use!

One feature I am missing is for a way to get the week number of a given date + startOfWeekDay.
Would be cool if this could also be included in the formatting tokens.

Bugfix deviceTZ undefined case error

Upgrading to version 0.0.14 caused the format function to malfunction.
I believe the issue lies within this piece of code.

src/format.ts

  // We need to apply an offset to the date so that it can be formatted as UTC.
  tz ??= deviceTZ()
  if (tz.toLowerCase() !== "utc") {
    inputDateOrOptions = removeOffset(
      inputDateOrOptions,
      offset(inputDateOrOptions, tz, "utc")
    )
  }

The content of deviceTZ is obtained from Intl.DateTimeFormat().resolvedOptions().timeZone, and this function requires the TZ environment variable to be set when executed in the local environment. If TZ is not set, deviceTZ will return undefined, causing tz to also become undefined, which results in an error when attempting to use tz.toLowerCase().

Also, if deviceTZ is undefined, tz needs to be specified in the FormatOptions, which means it can only be used in the FormatOptions pattern.

I think it would be beneficial to include a branching condition for cases where deviceTZ is undefined but tz is not set to UTC.

Incorrect formatting between local DST boundaries

The formatting function in this library works by applying an offset between the target and local timezones to the input Date object, then formatting that adjusted date object, which is technically representing a different moment in time. This causes problems when the resulting time lands in between a daylight saving time boundary, since there can be moments of time that are impossible to represent in certain timezones. For example, in American timezones, the time "March 10, 2024 at 2:30 AM" is impossible to represent, since the clocks jump from 1:59 AM to 3:00 AM. So the approach used by this library outputs an incorrect time around this boundary:

With this test script:

import { format } from '@formkit/tempo';

const date = new Date(Date.UTC(2024, 2, 10, 2, 30));

console.log(
  '@formkit/tempo:',
  format({
    date,
    format: { date: 'full', time: 'full' },
    tz: 'UTC',
  }),
);

console.log(
  'Intl.DateTimeFormat:',
  new Intl.DateTimeFormat('en-US', {
    dateStyle: 'full',
    timeStyle: 'full',
    timeZone: 'UTC',
  }).format(date),
);

The output with TZ=UTC is correct:

@formkit/tempo: Sunday, March 10, 2024 at 2:30:00 AM +0000
Intl.DateTimeFormat: Sunday, March 10, 2024 at 2:30:00 AM Coordinated Universal Time

But the output with TZ=America/New_York is incorrect:

@formkit/tempo: Sunday, March 10, 2024 at 3:30:00 AM +0000
Intl.DateTimeFormat: Sunday, March 10, 2024 at 2:30:00 AM Coordinated Universal Time

Are there any plans to support timezone formats like +-HH:mm in the parse function?

I've read the documentation, but I apologize if my knowledge falls short.
(validOffset)

I've noticed that the format 1982-05-17T07:44:00+0900 works as expected, but when using 1982-05-17T07:44:00+09:00, it leads to a format error stating Error: Invalid offset: +09:0 .

Moment.js documentation

Moment.js test code

date-fns

Feature Request: Relative Time

Would love to see a "format relative time" helper, like date-fns

See: https://github.com/date-fns/date-fns/blob/f4e22da16/src/formatRelative/index.ts#L54

Unnecessary code in bundles

Due to the lack of PURE annotations, extra code is included in bundles. Example: var tokens = new Map(...) is included and immediately thrown away (tokens var is not used, but the bundler is not sure if new Map can be safely omitted).

As I suppose tokens is indeed pure, this issue can be fixed by adding a few /* @__PURE__ */ annotations like this:

tempo/src/common.ts

Line 89 in 28a9539

export const tokens = new Map(

export const tokens = /* @__PURE__ */ new Map(
  /* @__PURE__ */ [...clockAgnostic, ...clock24, ...clock12].map((format) => {
    return [format[0], format]
  }),
)

More info:
Bundler — vite 5.1.4

Example on front page broken in German (and possibly other languages)

Quite a few examples on the front page throw an error in a German browser:

Date (Dienstag, 13. Februar 2024) does not match format (dddd, MMMM D, YYYY)

---

format() seems to default to the browser language. parse() should do that too in my opinion, and fall back to english if the local language fails.

[Feature request] Dates comparing

It would be nice to have methods for comparing dates like before, equal and after

Add full range of same{Unit} functions.

We currently have sameDay which is a helpful utility to compare two dates with reduced resolution, which I find helpful in many real-world applications. However, it would be nice to include a full range of these utilities:

• sameSecond
• sameMinute
• sameHour
• sameDay ✅
• sameYear

format YYYY-MM returns YYYY-M

https://codepen.io/tiamed/pen/PogGXKj

format(new Date(), 'YYYY-MM') should return '2024-03' but returned '2024-3'

Package's size is very big.

While publishing this good package, you ignored the docs directory but some of it's were published along side the library. This makes the size of this package unnecessarily big.

Currently it's: 1.12 MB
Estimated size without docs dir's content : 250kB

Generate exports size table for docs

@aleksandrjet’s work on #28 made me think it would be great to have an export size table on the docs, and perhaps the README.md that gets generated automatically on releases (could be generated on this github action).

FeatureReuet: Support for timezone format +-HH:mm in format token.

Thank you for addressing #38.

Regarding #38, when formatting, the timezone becomes +-HHmm.
I would be happy if I cloud also specify +-HH:mm.

Are there any plans to address this.
If it is addressed, what kind of Format Token is expected to be used?

Incorrect GMT offset when using FormatOptions with timezone

The following code will result in wrong time display.
The input is in UTC/Zulu time. The timezone shift occurs but the offset is not maintained and presented in the format.

format({
    date: new Date('2024-02-16T11:00:00Z'),
    format: 'YYYY-MM-DDTHH:mm:ssZ',
    tz: "Europe/Stockholm"
})

Result:
2024-02-16T12:00:00+0000

Your documentation examples should use a time of 13:00 or later to illustrate 12- versus 24-hour handling

The current documentation uses the time 11:45, which doesn't change based on locale. However, if you used, say, 14:34, the examples would be more illustrative when used across locales that default to 12- versus 24-hour time renderings.

yearStart and yearEnd may need to be added to types - v0.1.15

Currently if you try to use yearStart or yearEnd they will not compile in typescript, with the error:

Module '"@formkit/tempo"' has no exported member 'yearStart'.ts(2305)

It looks like it was implemented in: 8ae7a3b

But I'm not sure the types were added to the index.d.cts file.

Feature request: More timezone formats

Looks like the only option currently is "Z" for timezone offset (+0800).

Looking at Intl.DateTimeFormat['timezonename'] property, these could be useful:

• z: short generic (PT)
• zz: short (PST)
• zzz: long generic (Pacific Time)
• zzzz: long (Pacific Standard Time)

MDN reference
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#timezonename

CDN?

How to use as CDN?
thank you

Feature Request: Difference between datetimes

Hi I really like this new library, but for me to migrate to it I really need the functionality of manipulating dates.

Given two Dates:
D1 = 2010-06-09T15:32:00Z
D2 = 2010-06-09T11:32:00Z

It should return 4 hours (or eq. in days/min/sec)

Filtering out year still includes comma

Interesting project you have here!

I tried to filter the year from the "long" date style and expected it to look like March 30 but it rendered March 30, (note the extra comma).

I wasn't sure if this was unavoidable, but I wanted to bring it to your attention.

format({
  date: someDate,
  format: {date: "long"},
  partFilter: (part) => part.partName !== "year",
})

Feature Request: setXxx

I apologize if my knowledge is lacking.
I would like to set specific months or dates (absolute values).

While I can manage with addXxx (relative values) by working hard on calculations, I would prefer to have setXxx if possible.

See: https://momentjscom.readthedocs.io/en/latest/moment/02-get-set/20-set/

While the browser functionality suffices and writing a bit of source code is all it takes, having it return an immutable Date is appreciated.

https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Date/setHours

Support for milliseconds

Hi, I'd like to request the possibility to explicitly work with milliseconds during the various operations this library offers. The uppercase S is a common template token for parsing and formatting milliseconds, with the ability to vary the number of decimal places using multiple S (e.g. .S, .SS, .SSS).

Parsing a datetime with milliseconds already works when not using a custom format, for example parse("2022-08-03 16:56:54.477") returns the appropriate date object 2022-08-03T14:56:54.477Z.

Another thing I encountered is that tzDate seems to remove the milliseconds part of the date, both tzDate("2022-08-03 16:56:54.477", "Europe/Berlin") and tzDate(parse("2022-08-03 16:56:54.477"), "Europe/Berlin") return 2022-08-03T14:56:54.000Z.

(Other) Examples on front page broken

Relates to similar error found on #1.

Browser: Microsoft Edge Version 121.0.2277.113

For some reason tzDate() is not being recognized.

tzDate is not a function

Same error further down the page.

Also noticed an error when viewing in Brazilian Portuguese (same browser, same version):

Date (terça-feira, 13 de fevereiro de 2024) does not match format (dddd, MMMM D, YYYY)

validOffset is too permissive

The current validOffset code allows up to 39 hours and 69 minutes e.g. '+3969'. This is too wide, and makes the current validation incorrect.

The offsets being validated are Tempo defined offsets According to the documentation, these should be ISO 8601 compatible, and, according to the list of UTC offsets one only needs to go up to 15 hours and 45 minutes.

Current 'wide' validOffset implementation

export function validOffset(offset: striang) {
  const valid = /^([+-])[0-3][0-9][0-6][0-9]$/.test(offset)
  if (!valid) throw new Error(`Invalid offset: ${offset}`)
  return offset
}