{"id":23763807,"url":"https://github.com/tomashubelbauer/globe-design","last_synced_at":"2025-07-28T17:08:34.231Z","repository":{"id":107986136,"uuid":"265529633","full_name":"TomasHubelbauer/globe-design","owner":"TomasHubelbauer","description":"Microsoft Globe library refactoring design document","archived":false,"fork":false,"pushed_at":"2022-04-14T20:23:38.000Z","size":3,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-01T16:41:41.944Z","etag":null,"topics":["date-and-time","date-time","globe"],"latest_commit_sha":null,"homepage":"","language":"Markdown","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TomasHubelbauer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-20T10:25:08.000Z","updated_at":"2022-04-28T09:16:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"9c0e5a3d-116c-4e6a-a3be-ea89c9cbd216","html_url":"https://github.com/TomasHubelbauer/globe-design","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/TomasHubelbauer/globe-design","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fglobe-design","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fglobe-design/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fglobe-design/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fglobe-design/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomasHubelbauer","download_url":"https://codeload.github.com/TomasHubelbauer/globe-design/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fglobe-design/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267552097,"owners_count":24106000,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date-and-time","date-time","globe"],"created_at":"2024-12-31T22:13:35.957Z","updated_at":"2025-07-28T17:08:34.220Z","avatar_url":"https://github.com/TomasHubelbauer.png","language":"Markdown","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Globe Design\n\n[Globe](https://github.com/microsoft/globe) is a library me and my colleagues pulled out\nof an internal codebase in order to provide it to the open source audience, but also to\neventually improve it as it is based on code which has not been maintained and perhaps\ndesigned to a standard we want to eventually reach.\n\nThe purpose of the library is to provide an Intl-like mechanism, but one which takes into\nan account the operating system date and time formatting settings.\n\nIntl by itself takes perfect care of date and time localization, and we would use it bare\nif that was all we needed, but for a scenario where our code is running in Electron and\nnot the browser. It is still JavaScript, but it is running in a runtime which also allows\nexposing native code functions making the runtime more flexible than the browser. One of\nthe native APIs we make use of is one which provides our code with date and time format\nsettings as configured in the operating system. This information is not available in\nbrowser JavaScript APIs, so localization efforts in the browser end with Intl and indeed\nthat's where we end too, when our code is running in the browser. When running on the\ndesktop, though, there's further we can go to make the application feel more native. One\nof the improvements we can make is to query these operating system date and time format\nsettings and construct our Intl options such that the resultant formatted string follows\nthe same pattern the operating system uses when formatting date and time. Hopefully,\nmakes the user experience a tiny bit better and bridges the gap between our web-based\napplication and the native desktop experience a bit more.\n\nHow this is done is as follows:\n\n1. Query operating system date and time format strings\n2. Construct an Intl options object to mimic them\n3. Format date and time values this way to honor operating system date and time format\n\nUnfortunately, things are rarely this easy and we are dealing with a few complications:\n\n1. Operating systems make the date and time formatting strings configurable\n\n   The user is free to reorder the various date and time tokens in any way they please\n   and as a result the space of possible date and time format patterns is infinite.\n   Not only can users mix and match the date and time format tokens, they can also\n   interleave the pattern with verbatim strings to be included in the final pattern.\n  \n2. Operating systems provide a limited set of formatting strings not suitable for all\n   cases\n\n   As a part of the application user interface design, relative date and time labels\n   are a great way to present date and time information in a way that's quick to use\n   and contextual. The operating systems we support provide some variants of date and\n   time formats which differ in length and the amount of information contained, but\n   there are cases where none of these is a good match. As an example, all date format\n   strings usually include the year token, but it often makes sense to exclude the\n   year value from the date label if it matches the current year.\n   \nDue to #1 above, it is impossible to fully parse and represent the format strings in\na more structured way. Due to #2, the aforementioned is pretty much necessary as the\nstrings need to be processed to enable format options which enable formatting in ways\nwhich are not captured in the system-provided formattign strings, but are still in\ntheir \"spirit\" for a lack of a better term.\n \nFully parsing these formatting strings is impossible due to the various verbatim\ntokens users may choose to include in the formatting strings, so we've quickly ruled\nthat option our. However, not all is lost, as the fraction of people who tweak these\nsettings to very non-standard values is incredibly small and that largely limits the\npool of possible date and time formatting strings the operating system may provide\neven including the user adjustments. In theory, the common set of date and time format\nstrings across all cultures and with the most common tweaks is still pretty small.\n(Dozens, at most low hundreds of patterns? Depending on what we want to support.)\n\nFor formatting strings which fall out of this small common set, we can either opt\nout of formatting the date and time values so that the operating system formatting\nsettings are honored altogether, or we can opt out of processing them further to do\nthe desired transformations (such are dropping the year as mentioned above) and\ninstead use them verbatim. This way users with common patterns can benefit from the\nfurther processing which enables the UI niceties such as relative labels, but users\nwith uncommon patterns are not harmed in any way for having chosen unusual patterns.\nAt worst, they either get default browser behavior even on desktop or they get semi-\nrespective behavior (in terms of the patterns but not the transformations on them).\n\nThe users who do have common formatting strings benefit from Globe eventually\nrecognizing these formatting strings and providing structured information which\nallows the developers to do the transformations such as removing the year where\ndesired.\n\nAs of current, Globe does this in what we consider a slightly hacky way and we plan\non refactoring the library in time to not only simplify it, but also improve it so\nthat more common formatting patterns are correctly implemented and tested and the\nless common ones are not incorrectly interpreted resulting in broken labels.\n\n## Status\n\nThe design of the refactor is being worked out and I will update this document with\nour progress as we approach the final design document.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Fglobe-design","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomashubelbauer%2Fglobe-design","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Fglobe-design/lists"}