idle: add a grace period

toml-spec/spec/spec.generated.json

@@ -811,8 +811,25 @@
         "Vulkan"
       ]
     },
+    "GracePeriod": {
+      "description": "The definition of a grace period.\n\nOmitted values are set to 0. If all values are 0, the grace period is disabled.\n\n- Example:\n\n  ```toml\n  idle.grace-period.seconds = 3\n  ```\n",
+      "type": "object",
+      "properties": {
+        "minutes": {
+          "type": "integer",
+          "description": "The number of minutes the grace period lasts.",
+          "minimum": 0.0
+        },
+        "seconds": {
+          "type": "integer",
+          "description": "The number of seconds the grace period lasts.",
+          "minimum": 0.0
+        }
+      },
+      "required": []
+    },
     "Idle": {
-      "description": "The definition of an idle timeout.\n\nOmitted values are set to 0. If all values are 0, the idle timeout is disabled.\n\n- Example:\n\n  ```toml\n  idle.minutes = 10\n  ```\n",
+      "description": "The definition of an idle timeout.\n\nOmitted values are set to 0. If any value is explicitly set and all values are 0, the\nidle timeout is disabled.\n\n- Example:\n\n  ```toml\n  idle.minutes = 10\n  ```\n",
       "type": "object",
       "properties": {
         "minutes": {
@@ -824,6 +841,10 @@
           "type": "integer",
           "description": "The number of seconds before going idle.",
           "minimum": 0.0
+        },
+        "grace-period": {
+          "description": "The grace period after the timeout expires.\n\nDuring the grace period, the screen goes black but the outputs are not yet\ndisabled and the `on-idle` action does not yet run. This is a visual indicator\nthat the system will soon get idle.\n\nThe default is 5 seconds.\n",
+          "$ref": "#/$defs/GracePeriod"
         }
       },
       "required": []

toml-spec/spec/spec.generated.md

@@ -1670,12 +1670,51 @@ The string should have one of the following values:
 
 
 
+<a name="types-GracePeriod"></a>
+### `GracePeriod`
+
+The definition of a grace period.
+
+Omitted values are set to 0. If all values are 0, the grace period is disabled.
+
+- Example:
+
+  ```toml
+  idle.grace-period.seconds = 3
+  ```
+
+Values of this type should be tables.
+
+The table has the following fields:
+
+- `minutes` (optional):
+
+  The number of minutes the grace period lasts.
+
+  The value of this field should be a number.
+
+  The numbers should be integers.
+
+  The numbers should be greater than or equal to 0.
+
+- `seconds` (optional):
+
+  The number of seconds the grace period lasts.
+
+  The value of this field should be a number.
+
+  The numbers should be integers.
+
+  The numbers should be greater than or equal to 0.
+
+
 <a name="types-Idle"></a>
 ### `Idle`
 
 The definition of an idle timeout.
 
-Omitted values are set to 0. If all values are 0, the idle timeout is disabled.
+Omitted values are set to 0. If any value is explicitly set and all values are 0, the
+idle timeout is disabled.
 
 - Example:
 
@@ -1707,6 +1746,18 @@ The table has the following fields:
 
   The numbers should be greater than or equal to 0.
 
+- `grace-period` (optional):
+
+  The grace period after the timeout expires.
+  
+  During the grace period, the screen goes black but the outputs are not yet
+  disabled and the `on-idle` action does not yet run. This is a visual indicator
+  that the system will soon get idle.
+  
+  The default is 5 seconds.
+
+  The value of this field should be a [GracePeriod](#types-GracePeriod).
+
 
 <a name="types-Input"></a>
 ### `Input`

toml-spec/spec/spec.yaml

@@ -2293,7 +2293,8 @@ Idle:
   description: |
     The definition of an idle timeout.
     
-    Omitted values are set to 0. If all values are 0, the idle timeout is disabled.
+    Omitted values are set to 0. If any value is explicitly set and all values are 0, the
+    idle timeout is disabled.
     
     - Example:
     
@@ -2313,6 +2314,44 @@ Idle:
       integer_only: true
       minimum: 0
       required: false
+    grace-period:
+      description: |
+        The grace period after the timeout expires.
+        
+        During the grace period, the screen goes black but the outputs are not yet
+        disabled and the `on-idle` action does not yet run. This is a visual indicator
+        that the system will soon get idle.
+        
+        The default is 5 seconds.
+      ref: GracePeriod
+      required: false
+
+
+GracePeriod:
+  kind: table
+  description: |
+    The definition of a grace period.
+    
+    Omitted values are set to 0. If all values are 0, the grace period is disabled.
+    
+    - Example:
+    
+      ```toml
+      idle.grace-period.seconds = 3
+      ```
+  fields:
+    minutes:
+      description: The number of minutes the grace period lasts.
+      kind: number
+      integer_only: true
+      minimum: 0
+      required: false
+    seconds:
+      description: The number of seconds the grace period lasts.
+      kind: number
+      integer_only: true
+      minimum: 0
+      required: false
 
 
 RepeatRate: