# todo.group-by-due
Splits a todo list into the sections a planner shows, using todo.due-status
for every todo so the sections agree with the labels and the summary.
| Function | Order inside a section |
| --- | --- |
| `groupByDue(todos, today)` | Overdue, This week and Later by due date; the rest as given (below). Unchanged since 1.0.0. |
| `groupByDueWithOrder(todos, today, order)` | `order` `"due"`: the same as `groupByDue`. `"input"`: every section keeps the order the todos came in. |
Sections always come in this order, and only those with at least one todo are
returned:
| status | title |
| --- | --- |
| overdue | Overdue |
| today | Today |
| tomorrow | Tomorrow |
| this-week | This week |
| later | Later |
| none | No date |
| done | Done |
- **Overdue, This week and Later are sorted by due date**, earliest first,
because they span several dates. The sort is stable: todos with the same due
date keep their input order.
- **Today, Tomorrow, No date and Done keep the input order**, since every todo
in them has the same date (or none). So sort first by whatever you prefer
(priority, manual order, title) and the grouping keeps it inside each
section and among equal dates.
- The titles are English. A localised app maps `status` to its own strings.
- "This week" is the rest of the ISO week after tomorrow (see
todo.due-status): on Saturday and Sunday there is no This week section.
- `today` is checked even for an empty list, and a malformed or impossible
date anywhere is an error (dates.add-days's messages).
## New in 1.1.0: keeping the caller's order
`groupByDue` re-sorts the sections that span several dates, which is right
for a planner sorted by date but wrong for a list in the person's own
(manual, drag-and-drop) order: dragging a todo above another in Later would
snap back. `groupByDueWithOrder(todos, today, "input")` keeps the order the
todos came in, in every section, so sort first (todo.sort's manual order,
priority, title...) and the sections show that order. Which section a todo
goes in is the same either way.
`groupByDue` is now `groupByDueWithOrder(todos, today, "due")` and answers
exactly as 1.0.0 did: every 1.0.0 vector is kept. An `order` other than
`"due"` or `"input"` is an error (`order must be "due" or "input", found
"manual"`), checked before `today`.
1.0.0 was one function in one file; 1.1.0 is a group of two (see
`spec/AUTHORING.md`, Groups), so `import { groupByDue } from
"#fune/todo.group-by-due@^1"` keeps working.