Skip to content

Commit 6b33557

Browse files
pivoshenkopivoshenko
committed
feat: enhance clock with timezone support and formatting
1 parent 5f6017f commit 6b33557

File tree

20 files changed

+783
-90
lines changed

20 files changed

+783
-90
lines changed

‎.github/labels.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
color: B60205
4040

4141
- name: "type: bug"
42-
description: Indicates an unexpected problem or unintended behavior
42+
description: Indicates an unexpected problem or unintended behaviour
4343
color: D93F0B
4444

4545
- name: "type: documentation"

‎GLOSSARY.md‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,7 @@ A minimalistic and customisable startpage featuring the [**Catppuccin palettes**
4545
- Customisable startpage / bookmarks manager
4646
- Search bar with multiple engines
4747
- Weather widget
48+
- Clock widget with 12/24-hour format and multiple time zones support
4849

4950
# 🪵 Usage
5051

@@ -89,6 +90,36 @@ To select search engine, simply prefix the query with the corresponding `!<id>`.
8990
- `!g`: Google
9091
- `!d`: DuckDuckGo (default)
9192

93+
### ⏰ Clock
94+
95+
The startpage now features an enhanced clock component with:
96+
97+
- Support for 12-hour and 24-hour time formats
98+
- Multiple clocks for different time zones
99+
- Customisable formatting options
100+
- Locale support for regional time display
101+
102+
You can configure the clock format and add additional time zones in your `userconfig.js`:
103+
104+
```javascript
105+
clock: {
106+
format: "h:i", // 24-hour format
107+
icon_color: palette.maroon,
108+
},
109+
// Optional: Add multiple clocks for different time zones
110+
additionalClocks: [
111+
{
112+
label: "NYC", // Label for the clock
113+
timezone: "America/New_York", // IANA timezone name (handles DST automatically)
114+
format: "k:i p", // 12-hour format with leading zero (09:30 PM)
115+
locale: "en-US", // Locale for date/time formatting
116+
icon_color: palette.blue // Optional different icon color
117+
}
118+
],
119+
```
120+
121+
For full documentation of clock format options, [see](docs/CLOCK.md).
122+
92123
## 🖼️ Available Banners
93124

94125
| banner_01 | banner_02 | banner_03 | banner_04 |

‎docs/CLOCK.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Clock Component
2+
3+
- [Clock Component](#clock-component)
4+
- [Overview](#overview)
5+
- [Time Format Options](#time-format-options)
6+
- [Configuration](#configuration)
7+
- [Main Clock Configuration](#main-clock-configuration)
8+
- [Multiple Time Zones](#multiple-time-zones)
9+
- [IANA Timezone Names](#iana-timezone-names)
10+
- [Common Timezone Names](#common-timezone-names)
11+
- [Legacy Time Zone Offsets](#legacy-time-zone-offsets)
12+
13+
## Overview
14+
15+
The clock component has been enhanced to support multiple features:
16+
17+
- 12-hour and 24-hour time formats
18+
- Multiple clocks for different time zones displayed in a row
19+
- Customizable formatting options
20+
- Locale support for regional time display
21+
22+
## Time Format Options
23+
24+
The clock format uses an extended version of the `strftime` function with the following format specifiers:
25+
26+
| Format | Description | Example |
27+
| ------ | ----------------------------------- | --------------------- |
28+
| `H` | 24-hour format without leading zero | 9, 15 |
29+
| `h` | 24-hour format with leading zero | 09, 15 |
30+
| `K` | 12-hour format without leading zero | 9, 3 |
31+
| `k` | 12-hour format with leading zero | 09, 03 |
32+
| `i` | Minutes with leading zero | 05, 30 |
33+
| `M` | Minutes without leading zero | 5, 30 |
34+
| `s` | Seconds with leading zero | 08, 45 |
35+
| `S` | Seconds without leading zero | 8, 45 |
36+
| `p` | AM/PM uppercase | AM, PM |
37+
| `P` | AM/PM lowercase | am, pm |
38+
| `A` | Full weekday name | Monday, Tuesday |
39+
| `a` | Abbreviated weekday name | Mon, Tue |
40+
| `B` | Full month name | January, February |
41+
| `b` | Abbreviated month name | Jan, Feb |
42+
| `d` | Day of month with leading zero | 01, 28 |
43+
| `e` | Day of month without leading zero | 1, 28 |
44+
| `Y` | Full year | 2025 |
45+
| `y` | Two-digit year | 25 |
46+
| `z` | Full localized date and time | 5/31/2025, 9:30:45 PM |
47+
48+
## Configuration
49+
50+
### Main Clock Configuration
51+
52+
In your `userconfig.js` file, you can configure the main clock:
53+
54+
```javascript
55+
clock: {
56+
format: "k:i p", // 12-hour format with leading zero (09:30 PM)
57+
locale: "en-US", // Locale for date/time formatting
58+
icon_color: palette.maroon,
59+
},
60+
```
61+
62+
### Multiple Time Zones
63+
64+
To display additional clocks with different time zones:
65+
66+
```javascript
67+
additionalClocks: [
68+
// Method 1: Using IANA timezone names (preferred)
69+
{
70+
label: "NYC", // Label displayed next to the clock
71+
timezone: "America/New_York", // IANA timezone name (handles DST automatically)
72+
format: "k:i p", // Format (can be different from main clock)
73+
locale: "en-US", // Locale setting (optional)
74+
icon_color: palette.blue // Icon color (optional)
75+
},
76+
77+
// Method 2: Using timezone offset (legacy method)
78+
{
79+
label: "Paris",
80+
timezoneOffset: +1, // Hours offset from UTC (+1 for CET)
81+
format: "H:i", // 24-hour format without leading zero
82+
locale: "fr-FR",
83+
icon_color: palette.green
84+
}
85+
],
86+
```
87+
88+
## IANA Timezone Names
89+
90+
Using IANA timezone names (e.g., "America/New_York") is preferred over timezone offsets as they automatically handle Daylight Saving Time changes.
91+
92+
### Common Timezone Names
93+
94+
| Region | IANA Timezone Name |
95+
| ----------------------- | ------------------------------ |
96+
| London, UK | Europe/London |
97+
| Paris, France | Europe/Paris |
98+
| Berlin, Germany | Europe/Berlin |
99+
| Kyiv, Ukraine | Europe/Kyiv |
100+
| Dubai, UAE | Asia/Dubai |
101+
| New Delhi, India | Asia/Kolkata |
102+
| Bangkok, Thailand | Asia/Bangkok |
103+
| Singapore | Asia/Singapore |
104+
| Hong Kong | Asia/Hong_Kong |
105+
| Tokyo, Japan | Asia/Tokyo |
106+
| Sydney, Australia | Australia/Sydney |
107+
| New York, USA | America/New_York |
108+
| Chicago, USA | America/Chicago |
109+
| Denver, USA | America/Denver |
110+
| Los Angeles, USA | America/Los_Angeles |
111+
| Honolulu, USA | Pacific/Honolulu |
112+
| São Paulo, Brazil | America/Sao_Paulo |
113+
| Buenos Aires, Argentina | America/Argentina/Buenos_Aires |
114+
115+
### Legacy Time Zone Offsets
116+
117+
If you prefer using timezone offsets, you can still use the following values:
118+
119+
| City/Region | UTC Offset |
120+
| ------------------------- | ---------- |
121+
| London (GMT/UTC) | 0 |
122+
| Paris, Berlin, Rome (CET) | +1 |
123+
| Moscow | +3 |
124+
| Dubai | +4 |
125+
| New Delhi | +5.5 |
126+
| Bangkok | +7 |
127+
| Singapore, Hong Kong | +8 |
128+
| Tokyo | +9 |
129+
| Sydney | +10 |
130+
| New York (EST) | -5 |
131+
| Chicago (CST) | -6 |
132+
| Denver (MST) | -7 |
133+
| Los Angeles (PST) | -8 |
134+
| Honolulu | -10 |
135+
136+
Note: When using timezone offsets, the values provided are for standard time and don't automatically adjust for Daylight Saving Time.

‎src/common/actions.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
1-
// Provides actions for activating startpage components by name.
1+
// Provides actions for activating startpage components by name
22
class Actions {
33
/**
4-
* Activate a registered component by its name.
4+
* Activate a registered component by its name
55
* @param {string} componentName
66
* @returns {*}
77
*/

‎src/common/component.js‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,36 @@
1+
// Global registry of rendered components
12
const RenderedComponents = {};
23

3-
// Base class for all startpage components, providing shadow DOM, resource management, and rendering utilities.
4+
// Base class for all startpage components, providing shadow DOM, resource management, and rendering utilities
45
// Glossary: Component, Resource, Shadow DOM
56
class Component extends HTMLElement {
7+
// Element references for DOM manipulation
68
refs = {};
79

810
resources = {
11+
/** Google Fonts and other web fonts */
912
fonts: {
1013
roboto: '<link href="https://fonts.googleapis.com/css?family=Roboto:100,400,700" rel="stylesheet">',
1114
nunito: '<link href="https://fonts.googleapis.com/css?family=Nunito:200" rel="stylesheet">',
1215
raleway: '<link href="https://fonts.googleapis.com/css?family=Raleway:600" rel="stylesheet">',
1316
},
17+
/** Icon font libraries */
1418
icons: {
1519
material:
1620
'<link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet" type="text/css">',
1721
cryptofont: '<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/monzanifabio/cryptofont/cryptofont.css">',
1822
tabler: '<link rel="stylesheet" href="src/css/tabler-icons.min.css">',
1923
},
24+
/** CSS libraries and frameworks */
2025
libs: {
2126
awoo: '<link rel="stylesheet" type="text/css" href="src/css/awoo.min.css">',
2227
},
2328
};
2429

30+
/**
31+
* Initialise the component with shadow DOM
32+
* Creates an open shadow root for style encapsulation
33+
*/
2534
constructor() {
2635
super();
2736

@@ -30,21 +39,33 @@ class Component extends HTMLElement {
3039
});
3140
}
3241

42+
/**
43+
* Returns custom styles for the component
44+
* @returns {string|null} CSS styles or null
45+
*/
3346
style() {
3447
return null;
3548
}
3649

50+
/**
51+
* Returns the HTML template for the component
52+
* @returns {string|null} HTML template or null
53+
*/
3754
template() {
3855
return null;
3956
}
4057

58+
/**
59+
* Returns array of external resources to import
60+
* @returns {Array<string>} Array of resource imports
61+
*/
4162
imports() {
4263
return [];
4364
}
4465

4566
/**
46-
* Reference an external CSS file for the component.
47-
* Note: External style loading is not fully supported with web components and may cause flickering.
67+
* Reference an external CSS file for the component
68+
* Note: External style loading is not fully supported with web components and may cause flickering
4869
* @param {string} path
4970
* @returns {void}
5071
*/
@@ -53,7 +74,7 @@ class Component extends HTMLElement {
5374
}
5475

5576
/**
56-
* Return all the imports that a component requested.
77+
* Return all the imports that a component requested
5778
* @returns {Array<string>} imports
5879
*/
5980
get getResources() {
@@ -65,7 +86,7 @@ class Component extends HTMLElement {
6586
}
6687

6788
/**
68-
* Return inline style tag.
89+
* Return inline style tag
6990
* @returns {string}
7091
*/
7192
async loadStyles() {
@@ -77,15 +98,15 @@ class Component extends HTMLElement {
7798
}
7899

79100
/**
80-
* Build the component's HTML body.
101+
* Build the component's HTML body
81102
* @returns {string} html
82103
*/
83104
async buildHTML() {
84105
return (await this.loadStyles()) + (await this.template());
85106
}
86107

87108
/**
88-
* Create a reference proxy for manipulating DOM elements within the component's shadow DOM.
109+
* Create a reference proxy for manipulating DOM elements within the component's shadow DOM
89110
* @returns {Proxy<HTMLElement | boolean>}
90111
*/
91112
createRef() {
@@ -110,7 +131,7 @@ class Component extends HTMLElement {
110131
}
111132

112133
/**
113-
* Render the component's HTML and update references.
134+
* Render the component's HTML and update references
114135
* @returns {Promise<void>}
115136
*/
116137
async render() {

0 commit comments

Comments
 (0)