createTimelineGrouping

Description#

Derives grouped, sorted timeline bands from a flat item list.

Pure derivation: bands come out of one linkedSignal over the items accessor. Nothing is synced, nothing is written back, and the presenter never mutates its input array. The previous bands are read through the computation callback rather than a closure cache, so the result depends on the inputs and the prior value alone - never on how many times it ran.

Three properties make it usable as the organism's only data path:

• Defensive sort. Consumer data does not have to arrive sorted. The presenter sorts by the accessor date on every run using a stable sort, so items sharing a timestamp keep their input order in both directions.
• Local-calendar bucketing. day / week / month read local date fields rather than dividing the epoch, which is what keeps 23-hour and 25-hour DST days intact. Consumers who want UTC (or any other rule) pass a TimelineGroupingFn.
• Append-stability. Groups whose items are the same objects hand back the same band reference, and the signal carries a structural equal. Reuse is deliberately keyed on reference identity rather than on an id: a refetch returns new objects at the same ids, and reusing there would pin the band to a stale payload. Appending therefore leaves every other band's @for block untouched instead of re-rendering the whole timeline.

Reach for the DI token CNGX_TIMELINE_GROUPING_FACTORY rather than this function directly when the caller is a component - that is what makes the bucketing swappable per app or per component.

const grouping = createTimelineGrouping({
  items: this.events,
  dateAccessor: (event) => event.occurredAt,
  groupBy: this.groupBy,
});