Merge remote-tracking branch 'upstream/dev' into theme_switcher

docs/custom-api.md

@@ -0,0 +1,416 @@
+[Jump to function definitions](#functions)
+
+## Examples
+
+The best way to get an idea of how the templates work would be with a bunch examples. Here are the most common use cases:
+
+JSON response:
+
+```json
+{
+  "title": "My Title",
+  "content": "My Content",
+}
+```
+
+To access the two fields in the JSON response, you would use the following:
+
+```html
+<div>{{ .JSON.String "title" }}</div>
+<div>{{ .JSON.String "content" }}</div>
+```
+
+Output:
+
+```html
+<div>My Title</div>
+<div>My Content</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+{
+  "author": "John Doe",
+  "posts": [
+    {
+      "title": "My Title",
+      "content": "My Content"
+    },
+    {
+      "title": "My Title 2",
+      "content": "My Content 2"
+    }
+  ]
+}
+```
+
+To loop through the array of posts, you would use the following:
+
+```html
+{{ range .JSON.Array "posts" }}
+  <div>{{ .String "title" }}</div>
+  <div>{{ .String "content" }}</div>
+{{ end }}
+```
+
+Output:
+
+```html
+<div>My Title</div>
+<div>My Content</div>
+<div>My Title 2</div>
+<div>My Content 2</div>
+```
+
+Notice the missing `.JSON` when accessing the title and content, this is because the range function sets the context to the current array element.
+
+If you want to access the top-level context within the range, you can use the following:
+
+```html
+{{ range .JSON.Array "posts" }}
+  <div>{{ .String "title" }}</div>
+  <div>{{ .String "content" }}</div>
+  <div>{{ $.JSON.String "author" }}</div>
+{{ end }}
+```
+
+Output:
+
+```html
+<div>My Title</div>
+<div>My Content</div>
+<div>John Doe</div>
+<div>My Title 2</div>
+<div>My Content 2</div>
+<div>John Doe</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+[
+    "Apple",
+    "Banana",
+    "Cherry",
+    "Watermelon"
+]
+```
+
+Somewhat awkwardly, when the current context is a basic type that isn't an object, the way you specify its type is to use an empty string as the key. So, to loop through the array of strings, you would use the following:
+
+```html
+{{ range .JSON.Array "" }}
+  <div>{{ .String "" }}</div>
+{{ end }}
+```
+
+Output:
+
+```html
+<div>Apple</div>
+<div>Banana</div>
+<div>Cherry</div>
+<div>Watermelon</div>
+```
+
+To access an item at a specific index, you could use the following:
+
+```html
+<div>{{ .JSON.String "0" }}</div>
+```
+
+Output:
+
+```html
+<div>Apple</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+{
+    "user": {
+        "address": {
+            "city": "New York",
+            "state": "NY"
+        }
+    }
+}
+```
+
+To easily access deeply nested objects, you can use the following dot notation:
+
+```html
+<div>{{ .JSON.String "user.address.city" }}</div>
+<div>{{ .JSON.String "user.address.state" }}</div>
+```
+
+Output:
+
+```html
+<div>New York</div>
+<div>NY</div>
+```
+
+Using indexes anywhere in the path is also supported:
+
+```json
+{
+    "users": [
+        {
+            "name": "John Doe"
+        },
+        {
+            "name": "Jane Doe"
+        }
+    ]
+}
+```
+
+```html
+<div>{{ .JSON.String "users.0.name" }}</div>
+<div>{{ .JSON.String "users.1.name" }}</div>
+```
+
+Output:
+
+```html
+<div>John Doe</div>
+<div>Jane Doe</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+{
+    "user": {
+        "name": "John Doe",
+        "age": 30
+    }
+}
+```
+
+To check if a field exists, you can use the following:
+
+```html
+{{ if .JSON.Exists "user.age" }}
+  <div>{{ .JSON.Int "user.age" }}</div>
+{{ else }}
+  <div>Age not provided</div>
+{{ end }}
+```
+
+Output:
+
+```html
+<div>30</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+{
+    "price": 100,
+    "discount": 10
+}
+```
+
+Calculations can be performed on either ints or floats. If both numbers are ints, an int will be returned, otherwise a float will be returned. If you try to divide by zero, 0 will be returned. If you provide non-numeric values, `NaN` will be returned.
+
+```html
+<div>{{ sub (.JSON.Int "price") (.JSON.Int "discount") }}</div>
+```
+
+Output:
+
+```html
+<div>90</div>
+```
+
+Other operations include `add`, `mul`, and `div`.
+
+<hr>
+
+JSON response:
+
+```json
+{
+  "posts": [
+    {
+      "title": "Exploring the Depths of Quantum Computing",
+      "date": "2023-10-27T10:00:00Z"
+    },
+    {
+      "title": "A Beginner's Guide to Sustainable Living",
+      "date": "2023-11-15T14:30:00+01:00"
+    },
+    {
+      "title": "The Art of Baking Sourdough Bread",
+      "date": "2023-12-03T08:45:22-08:00"
+    }
+  ]
+}
+```
+
+To parse the date and display the relative time (e.g. 2h, 1d, etc), you would use the following:
+
+```
+{{ range .JSON.Array "posts" }}
+  <div>{{ .String "title" }}</div>
+  <div {{ .String "date" | parseTime "rfc3339" | toRelativeTime }}></div>
+{{ end }}
+```
+
+The `parseTime` function takes two arguments: the layout of the date string and the date string itself. The layout can be one of the following: "RFC3339", "RFC3339Nano", "DateTime", "DateOnly", "TimeOnly" or a custom layout in Go's [date format](https://pkg.go.dev/time#pkg-constants).
+
+Output:
+
+```html
+<div>Exploring the Depths of Quantum Computing</div>
+<div data-dynamic-relative-time="1698400800"></div>
+
+<div>A Beginner's Guide to Sustainable Living</div>
+<div data-dynamic-relative-time="1700055000"></div>
+
+<div>The Art of Baking Sourdough Bread</div>
+<div data-dynamic-relative-time="1701621922"></div>
+```
+
+You don't have to worry about the internal implementation, this will then be dynamically populated by Glance on the client side to show the correct relative time.
+
+The important thing to notice here is that the return value of `toRelativeTime` must be used as an attribute in an HTML tag, be it a `div`, `li`, `span`, etc.
+
+<hr>
+
+In some instances, you may want to know the status code of the response. This can be done using the following:
+
+```html
+{{ if eq .Response.StatusCode 200 }}
+  <p>Success!</p>
+{{ else }}
+  <p>Failed to fetch data</p>
+{{ end }}
+```
+
+You can also access the response headers:
+
+```html
+<div>{{ .Response.Header.Get "Content-Type" }}</div>
+```
+
+<hr>
+
+JSON response:
+
+```json
+{"name": "Steve", "age": 30}
+{"name": "Alex", "age": 25}
+{"name": "John", "age": 35}
+```
+
+The above format is "[ndjson](https://docs.mulesoft.com/dataweave/latest/dataweave-formats-ndjson)" or "[JSON Lines](https://jsonlines.org/)", where each line is a separate JSON object. To parse this format, you must first disable the JSON validation check in your config, since by default the response is expected to be a single valid JSON object:
+
+```yaml
+- type: custom-api
+  skip-json-validation: true
+```
+
+Then, to iterate over each object you can use `.JSONLines`:
+
+```html
+{{ range .JSONLines }}
+  <p>{{ .String "name" }} is {{ .Int "age" }} years old</p>
+{{ end }}
+```
+
+Output:
+
+```html
+<p>Steve is 30 years old</p>
+<p>Alex is 25 years old</p>
+<p>John is 35 years old</p>
+```
+
+For other ways of selecting data from a JSON Lines response, have a look at the docs for [tidwall/gjson](https://github.com/tidwall/gjson/tree/master?tab=readme-ov-file#json-lines). For example, to  get an array of all names, you can use the following:
+
+```html
+{{ range .JSON.Array "..#.name" }}
+  <p>{{ .String "" }}</p>
+{{ end }}
+```
+
+Output:
+
+```html
+<p>Steve</p>
+<p>Alex</p>
+<p>John</p>
+```
+
+## Functions
+
+The following functions are available on the `JSON` object:
+
+- `String(key string) string`: Returns the value of the key as a string.
+- `Int(key string) int`: Returns the value of the key as an integer.
+- `Float(key string) float`: Returns the value of the key as a float.
+- `Bool(key string) bool`: Returns the value of the key as a boolean.
+- `Array(key string) []JSON`: Returns the value of the key as an array of `JSON` objects.
+- `Exists(key string) bool`: Returns true if the key exists in the JSON object.
+
+The following helper functions provided by Glance are available:
+
+- `toFloat(i int) float`: Converts an integer to a float.
+- `toInt(f float) int`: Converts a float to an integer.
+- `toRelativeTime(t time.Time) template.HTMLAttr`: Converts Time to a relative time such as 2h, 1d, etc which dynamically updates. **NOTE:** the value of this function should be used as an attribute in an HTML tag, e.g. `<span {{ toRelativeTime .Time }}></span>`.
+- `now() time.Time`: Returns the current time.
+- `offsetNow(offset string) time.Time`: Returns the current time with an offset. The offset can be positive or negative and must be in the format "3h" "-1h" or "2h30m10s".
+- `duration(str string) time.Duration`: Parses a string such as `1h`, `24h`, `5h30m`, etc into a `time.Duration`.
+- `parseTime(layout string, s string) time.Time`: Parses a string into time.Time. The layout must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants). You can alternatively use these values instead of the literal format: "unix", "RFC3339", "RFC3339Nano", "DateTime", "DateOnly".
+- `parseLocalTime(layout string, s string) time.Time`: Same as the above, except in the absence of a timezone, it will use the local timezone instead of UTC.
+- `parseRelativeTime(layout string, s string) time.Time`: A shorthand for `{{ .String "date" | parseTime "rfc3339" | toRelativeTime }}`.
+- `add(a, b float) float`: Adds two numbers.
+- `sub(a, b float) float`: Subtracts two numbers.
+- `mul(a, b float) float`: Multiplies two numbers.
+- `div(a, b float) float`: Divides two numbers.
+- `formatApproxNumber(n int) string`: Formats a number to be more human-readable, e.g. 1000 -> 1k.
+- `formatNumber(n float|int) string`: Formats a number with commas, e.g. 1000 -> 1,000.
+- `trimPrefix(prefix string, str string) string`: Trims the prefix from a string.
+- `trimSuffix(suffix string, str string) string`: Trims the suffix from a string.
+- `trimSpace(str string) string`: Trims whitespace from a string on both ends.
+- `replaceAll(old string, new string, str string) string`: Replaces all occurrences of a string in a string.
+- `replaceMatches(pattern string, replacement string, str string) string`: Replaces all occurrences of a regular expression in a string.
+- `findMatch(pattern string, str string) string`: Finds the first match of a regular expression in a string.
+- `findSubmatch(pattern string, str string) string`: Finds the first submatch of a regular expression in a string.
+- `sortByString(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a string key in either ascending or descending order.
+- `sortByInt(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by an integer key in either ascending or descending order.
+- `sortByFloat(key string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a float key in either ascending or descending order.
+- `sortByTime(key string, layout string, order string, arr []JSON): []JSON`: Sorts an array of JSON objects by a time key in either ascending or descending order. The format must be provided in Go's [date format](https://pkg.go.dev/time#pkg-constants).
+- `concat(strings ...string) string`: Concatenates multiple strings together.
+- `unique(key string, arr []JSON) []JSON`: Returns a unique array of JSON objects based on the given key.
+
+The following helper functions provided by Go's `text/template` are available:
+
+- `eq(a, b any) bool`: Compares two values for equality.
+- `ne(a, b any) bool`: Compares two values for inequality.
+- `lt(a, b any) bool`: Compares two values for less than.
+- `lte(a, b any) bool`: Compares two values for less than or equal to.
+- `gt(a, b any) bool`: Compares two values for greater than.
+- `gte(a, b any) bool`: Compares two values for greater than or equal to.
+- `and(a, b bool) bool`: Returns true if both values are true.
+- `or(a, b bool) bool`: Returns true if either value is true.
+- `not(a bool) bool`: Returns the opposite of the value.
+- `index(a any, b int) any`: Returns the value at the specified index of an array.
+- `len(a any) int`: Returns the length of an array.
+- `printf(format string, a ...any) string`: Returns a formatted string.

docs/extensions.md

@@ -26,6 +26,9 @@ If you know how to setup an HTTP server and a bit of HTML and CSS you're ready t
 ### `Widget-Title`
 Used to specify the title of the widget. If not provided, the widget's title will be "Extension".
 
+### `Widget-Title-URL`
+Used to specify the URL that will be opened when the widget's title is clicked. If the user has specified a `title-url` in their config, it will take precedence over this header.
+
 ### `Widget-Content-Type`
 Used to specify the content type that will be returned by the extension. If not provided, the content will be shown as plain text.
 

docs/glance.yml

@@ -0,0 +1,105 @@
+pages:
+  - name: Home
+    # Optionally, if you only have a single page you can hide the desktop navigation for a cleaner look
+    # hide-desktop-navigation: true
+    columns:
+      - size: small
+        widgets:
+          - type: calendar
+            first-day-of-week: monday
+
+          - type: rss
+            limit: 10
+            collapse-after: 3
+            cache: 12h
+            feeds:
+              - url: https://selfh.st/rss/
+                title: selfh.st
+                limit: 4
+              - url: https://ciechanow.ski/atom.xml
+              - url: https://www.joshwcomeau.com/rss.xml
+                title: Josh Comeau
+              - url: https://samwho.dev/rss.xml
+              - url: https://ishadeed.com/feed.xml
+                title: Ahmad Shadeed
+
+          - type: twitch-channels
+            channels:
+              - theprimeagen
+              - j_blow
+              - piratesoftware
+              - cohhcarnage
+              - christitustech
+              - EJ_SA
+
+      - size: full
+        widgets:
+          - type: group
+            widgets:
+              - type: hacker-news
+              - type: lobsters
+
+          - type: videos
+            channels:
+              - UCXuqSBlHAE6Xw-yeJA0Tunw # Linus Tech Tips
+              - UCR-DXc1voovS8nhAvccRZhg # Jeff Geerling
+              - UCsBjURrPoezykLs9EqgamOA # Fireship
+              - UCBJycsmduvYEL83R_U4JriQ # Marques Brownlee
+              - UCHnyfMqiRRG1u-2MsSQLbXA # Veritasium
+
+          - type: group
+            widgets:
+              - type: reddit
+                subreddit: technology
+                show-thumbnails: true
+              - type: reddit
+                subreddit: selfhosted
+                show-thumbnails: true
+
+      - size: small
+        widgets:
+          - type: weather
+            location: London, United Kingdom
+            units: metric # alternatively "imperial"
+            hour-format: 12h # alternatively "24h"
+            # Optionally hide the location from being displayed in the widget
+            # hide-location: true
+
+          - type: markets
+            markets:
+              - symbol: SPY
+                name: S&P 500
+              - symbol: BTC-USD
+                name: Bitcoin
+              - symbol: NVDA
+                name: NVIDIA
+              - symbol: AAPL
+                name: Apple
+              - symbol: MSFT
+                name: Microsoft
+
+          - type: releases
+            cache: 1d
+            # Without authentication the Github API allows for up to 60 requests per hour. You can create a
+            # read-only token from your Github account settings and use it here to increase the limit.
+            # token: ...
+            repositories:
+              - glanceapp/glance
+              - go-gitea/gitea
+              - immich-app/immich
+              - syncthing/syncthing
+
+  # Add more pages here:
+  # - name: Your page name
+  #   columns:
+  #     - size: small
+  #       widgets:
+  #         # Add widgets here
+
+  #     - size: full
+  #       widgets:
+  #         # Add widgets here
+
+  #     - size: small
+  #       widgets:
+  #         # Add widgets here

docs/themes.md

@@ -53,6 +53,16 @@ theme:
   primary-color: 97 13 80
 ```
 
+### Gruvbox Dark
+![screenshot](images/themes/gruvbox.png)
+```yaml
+theme:
+  background-color: 0 0 16
+  primary-color: 43 59 81
+  positive-color: 61 66 44
+  negative-color: 6 96 59
+```
+
 ### Kanagawa Dark
 ![screenshot](images/themes/kanagawa-dark.png)
 ```yaml
@@ -72,6 +82,17 @@ theme:
   negative-color: 209 88 54
 ```
 
+### Dracula
+![screenshot](images/themes/dracula.png)
+```yaml
+theme:
+  background-color: 231 15 21
+  primary-color: 265 89 79
+  contrast-multiplier: 1.2
+  positive-color: 135 94 66
+  negative-color: 0 100 67
+```
+
 ## Light
 
 ### Catppuccin Latte

docs/v0.7.0-upgrade.md

@@ -0,0 +1,57 @@
+## Upgrading to v0.7.0 from previous versions
+
+In essence, the `glance.yml` file has been moved from the root of the project to a `config/` directory and you now need to mount that directory to `/app/config` in the container.
+
+### Before
+
+Versions before v0.7.0 used a `docker-compose.yml` that looked like the following:
+
+```yaml
+services:
+  glance:
+    image: glanceapp/glance
+    volumes:
+      - ./glance.yml:/app/glance.yml
+    ports:
+      - 8080:8080
+```
+
+And expected you to have the following directory structure:
+
+```plaintext
+glance/
+    docker-compose.yml
+    glance.yml
+```
+
+### After
+
+With the release of v0.7.0, the recommended `docker-compose.yml` looks like the following:
+
+```yaml
+services:
+  glance:
+    container_name: glance
+    image: glanceapp/glance
+    volumes:
+      - ./config:/app/config
+    ports:
+      - 8080:8080
+```
+
+And expects you to have the following directory structure:
+
+```plaintext
+glance/
+    docker-compose.yml
+    config/
+        glance.yml
+```
+
+## Why this change was necessary
+
+1. Mounting a file rather than a directory is not common practice and leads to some issues, such as creating a directory if the file is not present, which has tripped up multiple people and caused unnecessary confusion
+2. v0.7.0 added automatic reloads when the configuration file changes, which based on testing didn't work when mounting a single file
+3. v0.7.0 added the ability to include config files, so you'd have to make this change anyways if you wanted to take advantage of that feature
+
+Taking all of these into account, it felt like the right time to implement the change.