feat(agenda): highlight upcoming deadlines as @org.agenda.deadline.upcoming (#1138)

* feat(agenda): highlight upcoming deadlines as `@org.agenda.deadline.upcoming`

AI-assisted: Claude Sonnet 4.6 from GitHub Copilot

* docs: document newly added `@org.agenda.deadline.upcoming`

Author: vollowx

doc/orgmode.txt

@@ -2986,6 +2986,7 @@ The following highlight groups are used:
 - `@org.table.heading` - Table headings - linked to `@markup.heading`,
 - `@org.edit_src` - The highlight for the source content in an _Org_ buffer while it is being edited in an edit special buffer - linked to `Visual`,
 - `@org.agenda.deadline`: A item deadline in the agenda view - Parsed from `Error` (see note below)
+- `@org.agenda.deadline.upcoming`: A item upcoming deadline in the agenda view - Parsed from `WarningMsg` (see note below)
 - `@org.agenda.scheduled`: A scheduled item in the agenda view - Parsed from `DiffAdd` (see note below)
 - `@org.agenda.scheduled_past`: A item past its scheduled date in the agenda view - Parsed from `WarningMsg` (see note below)
 - `@org.agenda.time_grid`: Time grid line - Parsed from `WarningMsg` (see note below)

docs/configuration.org

@@ -2961,6 +2961,7 @@ The following highlight groups are used:
 - =@org.table.heading= - Table headings - linked to =@markup.heading=,
 - =@org.edit_src= - The highlight for the source content in an /Org/ buffer while it is being edited in an edit special buffer - linked to =Visual=,
 - =@org.agenda.deadline=: A item deadline in the agenda view - Parsed from =Error= (see note below)
+- =@org.agenda.deadline.upcoming=: A item upcoming deadline in the agenda view - Parsed from =WarningMsg= (see note below)
 - =@org.agenda.scheduled=: A scheduled item in the agenda view - Parsed from =DiffAdd= (see note below)
 - =@org.agenda.scheduled_past=: A item past its scheduled date in the agenda view - Parsed from =WarningMsg= (see note below)
 - =@org.agenda.time_grid=: Time grid line - Parsed from =WarningMsg= (see note below)

lua/orgmode/agenda/agenda_item.lua

@@ -223,7 +223,7 @@ function AgendaItem:get_hlgroup()
     if self.is_today and self.headline_date:is_after(self.date, 'day') then
       local diff = math.abs(self.date:diff(self.headline_date))
       if diff <= FUTURE_DEADLINE_AS_WARNING_DAYS then
-        return hl_map.warning
+        return hl_map.upcoming_deadline
       end
       return nil
     end

lua/orgmode/colors/highlights.lua

@@ -87,6 +87,7 @@ function M.define_agenda_colors()
   local keyword_colors = colors.get_todo_keywords_colors()
   local c = {
     deadline = '@org.agenda.deadline',
+    upcoming_deadline = '@org.agenda.deadline.upcoming',
     ok = '@org.agenda.scheduled',
     warning = '@org.agenda.scheduled_past',
   }
@@ -205,6 +206,7 @@ function M.get_agenda_hl_map()
     TODO = '@org.keyword.todo',
     DONE = '@org.keyword.done',
     deadline = '@org.agenda.deadline',
+    upcoming_deadline = '@org.agenda.deadline.upcoming',
     ok = '@org.agenda.scheduled',
     warning = '@org.agenda.scheduled_past',
     priority = config:get_priorities(),

lua/orgmode/colors/init.lua

@@ -59,6 +59,10 @@ M.get_todo_keywords_colors = function()
       gui = M.from_hex(error):lighten_by(0.1):to_rgb(),
       cterm = 9,
     },
+    upcoming_deadline = {
+      gui = M.from_hex(warning):lighten_by(0.1):to_rgb(),
+      cterm = 11,
+    },
     ok = {
       gui = M.from_hex(ok):lighten_by(0.1):to_rgb(),
       cterm = 10,

tests/plenary/agenda/agenda_item_spec.lua

@@ -92,12 +92,12 @@ describe('Agenda item', function()
       assert.is.Nil(agenda_item:get_priority_hlgroup())
       assert.are.same('In 9 d.:', agenda_item.label)
 
-      -- future without warning within the default warning days and less than 6 days (highlights as warning)
+      -- future without warning within the default warning days and less than 6 days (highlights as upcoming warning)
       headline = generate(string.format('DEADLINE: <%s>', today:add({ day = 6 }):to_string()))
       agenda_item = AgendaItem:new(headline:get_all_dates()[1], headline, today)
       assert.is.True(agenda_item.is_valid)
       assert.is.same(hl_map.TODO, agenda_item:get_todo_hlgroup())
-      assert.is.same(hl_map.warning, agenda_item:get_hlgroup())
+      assert.is.same(hl_map.upcoming_deadline, agenda_item:get_hlgroup())
       assert.is.Nil(agenda_item:get_priority_hlgroup())
       assert.are.same('In 6 d.:', agenda_item.label)
 
@@ -108,12 +108,12 @@ describe('Agenda item', function()
       assert.is.same(hl_map.TODO, agenda_item:get_todo_hlgroup())
       assert.are.same('In 9 d.:', agenda_item.label)
 
-      -- future with warning within the defined warning period and less than 6 days (highlights as warning)
+      -- future with warning within the defined warning period and less than 6 days (highlights as upcoming deadline)
       headline = generate(string.format('DEADLINE: <%s -10d>', today:add({ day = 6 }):to_string()))
       agenda_item = AgendaItem:new(headline:get_all_dates()[1], headline, today)
       assert.is.True(agenda_item.is_valid)
       assert.is.same(hl_map.TODO, agenda_item:get_todo_hlgroup())
-      assert.is.same(hl_map.warning, agenda_item:get_hlgroup())
+      assert.is.same(hl_map.upcoming_deadline, agenda_item:get_hlgroup())
       assert.is.Nil(agenda_item:get_priority_hlgroup())
       assert.are.same('In 6 d.:', agenda_item.label)
 

tests/plenary/colors/colors_spec.lua

@@ -45,6 +45,7 @@ describe('Colors', function()
       DONE = { gui = '#00FF00', cterm = 2 },
       TODO = { gui = '#FF0000', cterm = 1 },
       deadline = { gui = '#ff1a1a', cterm = 9 },
+      upcoming_deadline = { gui = '#ff981a', cterm = 11 },
       ok = { gui = '#1aff1a', cterm = 10 },
       warning = { gui = '#ff981a', cterm = 11 },
     }, todo_keywords_colors)